Par tipů na lepší názvosloví

Upozornění: Tohle vlákno je hodně staré a informace nemusí být platné pro současné Nette.
David Grudl
Nette Core | 7790
+
0
-

Ze školení si odnáším i postřehy stran toho, že některé názvy mohou působit v hlavách začátečníků zmatek, kolikrát sám napíšu název špatně. Mám tu pár horkých kandidátů na přejmenování. Ale často netuším, co si s nimi počít.

Vymyslet dobré názvosloví fakt není tak snadné, chce si to vyzkoušet přímo v kódu a zvážit možné kolize, proto prosím nestřílejte hned od boku

  • „namespaces“ v Session: jmenné prostory v PHP 5.3 jsou ještě příliš čerstvé a dochází ke zmatení pojmů, když namespaces v Session představují něco zcela jiného změněno
  • Control::invalidateControl() a méně často používaní sourozenci validateControl() a isControlInvalid() jsou jasní kandidáti na přejmenování, ale v nových názvech by bylo asi lepší se vyhnout slovu render.
  • Filtry u šablon: historický název, dnes je filtr spíš „template engine“ a otázkou je, jestli má smysl jich registrovat více
  • Helpery u šablon: historický název, avšak kdo skutečně nazývá pravou část makra např. {$price|money} slovem helper?
  • Form::setDefaults() – není očekávanější spíš setDefaultValues()?
  • Form::IMAGE jakožto validátor pro obrázky JPEG, PNG a GIF by se spíš mohl jmenovat třeba WEBIMAGE
  • obdobně Nette\Http\FileUpload::isImage() → isWebImage() ?
  • SelectBox::skipFirst() – historický název, který neodpovídá současnému používání s parametrem změněno na setPrompt()
  • Form::$onSubmit zahrnuje i to, že formulář musí být validní, což není zřejmé. Zvolit jinou událost? změněno na $onSuccess
  • Form::addFile() změněno na addUpload(), addImage() a případně i addSubmit() nevystihují podstatu. Nebyl by lepší addUpload, addImageButton?
  • Form::addDynamic, addElastic či addRepeater? bude použit addRepeater()
  • nebylo by lepší nahradit Image::FILL pro funkci resize() za třeba OVERLAP?
  • Nette\Database\Table\Selection: metody get() vs find() vs fetch() jsou neintuitivní, co která z nich dělá?
  • User::setAuthenticationHandler() – z hlavy to neumím napsat, nebyl by lepší název podle interface User::setAuthenticator() a obdobně User::setAuthorizator() ? změněno
  • nové Cache::start() pro kešování výstupu je poněkud zavádějící
  • z chystaných věcí: Presenter vyžadující, aby uživatel byl přihlášen, se bude moci označit anotací. Jakou? Název by neměl vzbuzovat dojem, že presenter je „zabezpečený“.
  • objeví se defaultní presentery (např. ErrorPresenter), jaký jim dát název modulu?
Filip Procházka
Moderator | 4668
+
0
-

Form::setDefaults() – není očekávanější spíš setDefaultValues()?

Spíš je matoucí, že na prvku se to jmenuje jinak setDefaultValue(). A jestli tak, nebo tak, už asi není tak stěžejní, ale určitě sjednotit.

User::setAuthenticationHandler() – z hlavy to neumím napsat, nebyl by lepší název podle interface User::setAuthenticator() a obdobně User::setAuthorizator() ?

Díky těmhle funkcím jsem začal vnímat rozdíl mezi těmi slovy :) Ale je to psycho no…

mkoubik
Člen | 728
+
0
-

David Grudl napsal(a):

  • z chystaných věcí: Presenter vyžadující, aby uživatel byl přihlášen, se bude moci označit anotací. Jakou? Název by neměl vzbuzovat dojem, že presenter je „zabezpečený“.

Já na tohle používám abstraktní AuthenticatedPresenter takže /** @authenticated */ by mi proto přišlo intuitivní, ale možná je to jenom můj zvyk.

paranoiq
Člen | 392
+
0
-
  • lepší by bylo session context, ale může se to plést s DI/Context, případně session section, což je zase jazykolam
  • invalid control je opravdu zavádějící. actual(ize)/recent/obsolete atp. jsou problémová. co updateControl(), isControlUpToDate(), setControlUpToDate(). dál je možnost inspirovat se u špinavých paměťových stránek: taintControl(), isControlTainted()untaintControl()
  • template helper se mi zdá ok
  • nový terminus technicus „webový obrázek“ bych raději nezaváděl. tohle už mi připadá jako boj o pomazánkové …
  • Form::$onSuccess?
  • Form::addElastic() určitě ne. natahování není totéž co opakování/přidávání
  • @authenticated (vs případné @authorized(resuorce, action)). kdo rozdíl nevnímá, tomu těžko pomoci. pokoušet se to opsat přes anonymní atp. asi nepůjde
  • modul Nette

a hlavně nestřílet od boku ;]

Patrik Votoček
Člen | 2221
+
0
-

David Grudl napsal(a):

  • „namespaces“ v Session: jmenné prostory v PHP 5.3 jsou ještě příliš čerstvé a dochází ke zmatení pojmů, když namespaces v Session představují něco zcela jiného

collection?

  • Helpery u šablon: historický název, avšak kdo skutečně nazývá pravou část makra např. {$price|money} slovem helper?

spíš „modifikátor“

  • Form::setDefaults() – není očekávanější spíš setDefaultValues()?

je jedno jak se to jmenuje ale ať je to stejné s BaseControl::setDefaultValue()

  • Form::IMAGE jakožto validátor pro obrázky JPEG, PNG a GIF by se spíš mohl jmenovat třeba WEBIMAGE
  • obdobně Nette\Http\FileUpload::isImage() → isWebImage() ?

stávající je podle mě OK… WEBIMAGE se mě nelíbí

  • Form::$onSubmit zahrnuje i to, že formulář musí být validní, což není zřejmé. Zvolit jinou událost?

Form::$onValidSubmit ?

  • nové Cache::start() pro kešování výstupu je poněkud zavádějící

Co to to?

  • z chystaných věcí: Presenter vyžadující, aby uživatel byl přihlášen, se bude moci označit anotací. Jakou? Název by neměl vzbuzovat dojem, že presenter je „zabezpečený“.

User::isLoggedIn()@loggedIn

  • objeví se defaultní presentery (např. ErrorPresenter), jaký jim dát název modulu?

Žádný? spíš zavést namespace App

22
Člen | 1478
+
0
-
  • session section
  • helper nechat
  • $form->setDefaultValues() → $form->fillDefaultValues()
  • Form::IMAGE nechat
  • onValidSubmit[]
  • skipFirst() nechat
  • addSubmitButton, addImageButtonm, addFileInput
  • addDynamic() nechat
  • setAuthenticator(), setAuthorizator()
  • @logInRequirement
  • název modulu App nebo Default
norbe
Backer | 403
+
0
-

David Grudl napsal(a):

  • Form::setDefaults() – není očekávanější spíš setDefaultValues()?

Přidávám hlas pro setDefaultValues

  • Form::IMAGE jakožto validátor pro obrázky JPEG, PNG a GIF by se spíš mohl jmenovat třeba WEBIMAGE
  • obdobně Nette\Http\FileUpload::isImage() → isWebImage() ?

Tohle mi přijde jako z bláta do louže. Kde je specifikované co je web image? Budu si muset pamatovat úplně stejně jako u samotného image, že se jedná pouze o JPEG,PNG a GIF…

  • Form::addDynamic, addElastic či addRepeater?

Zvolil bych addDynamic – lidé vytvářejí témata s návy typu „dynamické formuláře“, proto mi přijde slovo dynamic jako nejlépe výstižné (zvážil bych možná addDynamicPart)

  • User::setAuthenticationHandler() – z hlavy to neumím napsat, nebyl by lepší název podle interface User::setAuthenticator() a obdobně User::setAuthorizator() ?

Tohle si myslím že by byla drobná změna k lepšímu, ale obejdu se bez toho…

  • z chystaných věcí: Presenter vyžadující, aby uživatel byl přihlášen, se bude moci označit anotací. Jakou? Název by neměl vzbuzovat dojem, že presenter je „zabezpečený“.

Pro tohle používám anotaci @authenticated, pokud pak potřebuji vyjímku použiju u action/render metody @unauthenticated

redhead
Člen | 1313
+
0
-
  • IMAGE nechat, WEBIMAGE je takové divné.
  • @authenticated
  • addDynamic()
  • $onValidSubmit
  • helper nevadí, ale když to musí bejt tak modifikátor
  • setDefaults() → setDefaultValues()

paranoiq napsal(a):
updateControl(), isControlUpToDate(), setControlUpToDate().

Líp by se mi určitě četlo isControlUpdated() a setControlUpdated()

Ondřej Brejla
Člen | 746
+
0
-
  • session collection? To snad né…to smrdí kolekcema ;-)
  • modifikátor? To snad také ne… Vykřikněte v místnosti plné programátorů „Modifikátor!!!“ a věřím tomu, že sborově odpoví „Přístupu!!!“…helper mi přijde ok.
  • Rozhodně onValidSubmit[]…když používám onSubmit[], tak si vždycky říkám…„Jojo, to je vlastně ta událost, kde v názvu chybí slovo“…:-)
  • setDefaultValues() je krásně vystihující.

…na ostatní zatím nemám názor…

Edit:

  • session…jen mi ještě tak blesklo hlavou, co třeba jenom space? Možná je to úplná ptákovina, možná ne…kdo ví…je to myšlenka úterní půlnoci :-) Ještě mě teda napadlo scope, ale to je možná ještě víc mimo…nebo ne? :-)

Editoval Ondřej Brejla (10. 5. 2011 23:40)

paranoiq
Člen | 392
+
0
-

lepší než modifikátor by byl převaděčspojitosti ;-]

Nox
Člen | 378
+
0
-
  • modifikátor je podle mě odpovídající označení
  • onValidSubmit zní ok
  • WEBIMAGE určitě ne – co to je „web image“?
  • addDynamic zní univerzálněji, addRepeater nezní špatně ale neznalý nevim jestli pochopí…
  • addUpload zní dobře
jazby
Člen | 44
+
0
-

Taky se přidávám

++ Modifikátor

++ OnValidSubmit

++ addDynamic

++ @authenticated

++ setDefaultValues()

-- WebImage

Ondřej Mirtes
Člen | 1536
+
0
-

isImage(), Form::IMAGE nechat, z názvu a kontextu je jasné, co dělají.

Helpery také nechat, nevidím důvod pro přejmenování. Z názvu je opět jasné, jaký je jejich účel.

Matúš Matula
Člen | 248
+
0
-
  • helper je fajn, nechat
  • setDefautls() premenovat na setDefaultValues()
  • addFile(), addImage() a addSubmit() na addFileUpload(), addImageButton(), addSubmitButton()
  • onValidSubmit ++
  • addDynamic ++
Honza Marek
Člen | 1664
+
0
-

David Grudl napsal(a):

  • Helpery u šablon: historický název, avšak kdo skutečně nazývá pravou část makra např. {$price|money} slovem helper?

Já jo. Ale je pravda, že jsem se to naučil od Nette, tak nevím, jestli je to správně.

  • Form::$onSubmit zahrnuje i to, že formulář musí být validní, což není zřejmé. Zvolit jinou událost?

Pokud bude onSubmit zachováno s tím, že bude přijímat i nevalidní data, tak tohle je naprosto zásadní nekompatibilita, která může nasekat bezpečnostní díry do webů nic netušících updatujících uživatelů. Navíc mi současný onSubmit naprosto vyhovuje, proč bych měl zpracovávat nevalidní formulář?

  • Form::addDynamic, addElastic či addRepeater?

asi Repeater

  • User::setAuthenticationHandler() – z hlavy to neumím napsat, nebyl by lepší název podle interface User::setAuthenticator() a obdobně User::setAuthorizator() ?

asi jo

  • objeví se defaultní presentery (např. ErrorPresenter), jaký jim dát název modulu?

Nette

JakubJarabica
Gold Partner | 184
+
0
-
  • helpery: Bežne používam, vďaka Nette/Smarty
  • setDefaultValues()
  • Webimage je čudné
  • addFileInput, addSubmitButton, addImageButton
  • addDynamic jednoznačne(ešte lepšie addDynamicContainer, i keď dlhé – ale používané to bude sem-tam)

@HonzaMarek: onInvalidSubmit napríklad do A/B testovania, prípadne sledovania konverzií formov(trebárs si budeš logovať aká bola error a čo bolo vyplnené – i keď to bude chcieť aj napojenie na JS event), onValidSubmit by bol krásny event, ktorý by bol sám o sebe popisný.

David Grudl
Nette Core | 7790
+
0
-
  • session: section se mi líbi asi nejvíc
  • Form::$onSubmit → $onSuccess jsem měl v plánu (a také + $onError). Zpětnou kompatibilitu je třeba zachovat. Návrh: $onSubmit, pokud je prázdné $onSuccess, se bude chovat po staru, jinak ponovu.
  • Form::addRepeater nejpřesněji vystihuje podstatu prvku, pojem dynamický je širší a zahrnuje třeba i provázané selectboxy apod.
  • anotace pro presenter a metody: @authenticated bez napovídání nedám :-) Asi by bylo vhodnější @loggedIn podle vzoru $user->loggedIn. Šlo by to použít i ve variantách jako @loggedIn(role = admin). Jak ale zapsat výjimku, když by jedna metoda neměla být loggedIn?
  • Form::setDefaultValues() mi připadá lepší, proč varianta bez „s“?
  • Form::addFileUpload(), addImageButton() a addSubmitButton() je takřka jednomyslná shoda. Ještě mě napadá, že v názvu addHidden() chybí podstatné jméno.
  • Control::invalidateControl() – co třeba nějaký paintControl, repaint, redraw?
  • SelectBox::skipFirst() – navrhuji setPrompt(). Připomíná mi to staré dobré časy s DOSem ;-)
  • WEBIMAGE: je to vlastně totéž jako (dříve používané) webcolors. PHP umí zpracovat a prohlížeče zobrazit jen tři formáty, kdežto obrázek může být také BMP a TIFF (možná ještě ICO, nic dalšího se nepoužívá). Tohle je potřeba v názvosloví nějak postihnout.

norbe napsal(a):

Tohle mi přijde jako z bláta do louže. Kde je specifikované co je web image?

Zde http://www.w3.org/Graphics/ a http://www.w3.org/…objects.html#…

Nox
Člen | 378
+
0
-
  • redraw() je supr
  • loggedIn zní divně jako označení presenteru, neloguje se presenter ale uživatel…

Editoval Nox (11. 5. 2011 16:29)

22
Člen | 1478
+
0
-

co refresh()?

Patrik Votoček
Člen | 2221
+
0
-

David Grudl napsal(a):

  • anotace pro presenter a metody: @authenticated bez napovídání nedám :-) Asi by bylo vhodnější @loggedIn podle vzoru $user->loggedIn. Šlo by to použít i ve variantách jako @loggedIn(role = admin). Jak ale zapsat výjimku, když by jedna metoda neměla být loggedIn?

tak tak… @guest (ale nevím nevím)?

  • WEBIMAGE: je to vlastně totéž jako (dříve používané) webcolors. PHP umí zpracovat a prohlížeče zobrazit jen tři formáty, kdežto obrázek může být také BMP a TIFF (možná ještě ICO, nic dalšího se nepoužívá). Tohle je potřeba v názvosloví nějak postihnout.

Pokud beru PHP umí zpracovat … jen tři formáty tak IMAGE dostačuje Form::IMAGE přece píšu v PHP takže vím že to je jenom pro „webimage“.

kravčo
Člen | 721
+
0
-
/**
 * @user(loggedIn, role = admin)
 */
Presenter
{
    /**
     * @user()
     */
    method()
}

Nebolo by na mieste zaviesť i prefix, ktorý by riešil prípadné kolízie s phpdoc, tak ako je to pri latte? Písanie @n:user() je trochu krkolomné, ale napr. @@user() alebo n@user() by sa písalo o čosi ľahšie…

dcepelik
Člen | 36
+
0
-

Souhlasím s Form::setDefaultValues a líbí se mi WEBIMAGE.

Modifikátor je určitě lepší označení než helper. Například CakePHP chápe helper jako objekt, který ve srovnání s Nette provádí v rámci šablony poměrně kaskadérské kousky (např. se stará o kompletní stavění formulářů). Když se nad tím zamyslím, přijde mi stejně nejlepší formatter.

U selectu bych se příkláněl spíše k Select::setEmptyValue() – co to koneckonců je (první položka), když ne prázdná hodnota, která, je-li zvolena, je vyhodnocena jako „žádný vstup uživatele“? Pěkně by se to sjednotilo s ostatními ovládacími prvky na formulářích.

Je příjemné mít možnost podílet se, třebaže jen malou měrou, na směru, kterým se Nette ubírá.

norbe
Backer | 403
+
0
-

David Grudl napsal(a):
Zde http://www.w3.org/Graphics/ a http://www.w3.org/…objects.html#…

V prvním odkazu vidím např. i formát SVG (který se mi právě při použití webimage ihned vybavil), které podporované není. V druhém příkazu je naopak uvedeno „Examples“ tedy příklady, nikoliv výčet všech možných.

Jako největší argument ale vidím to, že když chci někde přidat validaci pro obrázky, rozhodně mne nenapadne začínat slovem WEB a nebude mi teda fungovat napovídání v IDE (jestli jsem výjimka tak ať se to klidně přejmenuje).

na1k
Člen | 288
+
0
-

A nemůže být helper prostě jenom „makro“?

Nevím jak vy, ale mně se už od začátku strašlivě pletou „template filters“ a „template helpers“. Vždycky musím dohledávat, které jsou ty runtime :-p

paranoiq
Člen | 392
+
0
-
  • SelectBox::skipFirst(): po vzoru textboxů v HTML5 by mohlo být setPlaceholder()
  • v názvu addHidden() chybí podstatné jméno: hidden je vlastně blbý název přejatý z HTML. co vymyslet lepší? addVariable(), addParameter()
Matúš Matula
Člen | 248
+
0
-

@paranoiq: podstatne meno tam chyba, ale nevymyslal by som uplne nove nazvoslovie pre zauzivanu vec akou je hidden input. ked tvorim html formular, tak by to malo podla mna korespondovat.

xDexter
Člen | 13
+
0
-

Form::addDynamic, addElastic či addRepeater?

Jsem pro ponechání addDynamic, popř. addRepeater.
U addElastic by nebylo jasné jakou vlastnost form má.

Honza Marek
Člen | 1664
+
0
-

Nepřijde vám šílená dvojice Nette\Http\(I)User a Nette\Security\(I)Identity? I když to nastřelím hrubě od boku, tak by snad z názvů NejakejNamespace\(I)SecurityContext a NejakejNamespace\(I)User bylo lépe jasné, co mají ty dvě věci na starosti.

Ascaria
Člen | 187
+
0
-

Zdravím,

nenašel jsem lepší sekci, než je tato stará.

IE je schopný mime jpegu předat jako image/pjpeg.
Chtělo by to statickou metodu, která určí, zda-li jde o webimage či ne.

David Grudl
Nette Core | 7790
+
0
-

Typ uvedený prohlížečem Nette ignoruje.