Rozšířit informaci o chybách a výjímkách

jasir

Při pročítání fóra člověk snadno objeví, že dotazy se často opakují a často začínají nějak takto:

novej napsal: Pokouším se o vytvoření formuláře podle examplů pomocí nových továrniček, ale Nette stále vyhazuje výjímku „nemohu najít componentu mujformulář“. Nemohu s tím pohnout, strašně už se s tim 2 hodiny peru, dyť přece nejsem tak blbej… atd..

Pamatujete ne?

Navrhuji, aby každá vyhozená exception / chyba obsahoval link do naší wiki dokumentace na nette.org na vlastní stránku pojmenovanou jménem vyjímky.

Na této stránce by se dále klasicky shromažďovala řešení na jednotlivé varianty problémů.
Vytvořila by se tak postupně seznam všech chyb, které nette vyhazuje s jejich řešením, odkazy do fóra, na dokumentaci atd.

Každá exception by obsahovala tento link a ze stránky laděnky by se dalo kliknout rovnout na odkaz do wiki.

A když už jsme u toho, každá třída Nette Frameworku a každá metoda si zaslouží svojí moderovanou diskuzi zde na fóru. Myslím, že komunita zde je dost silná na to, aby v krátkém čase dokazála uchavat všechna společne nalezená řešení na jednom, jasně definovaném místě. Myslím, že by to byl pěkný doplněk Davidově blížícímu se měsíčnímu usílí na sepsání kompletní dokumentace.

Co vy na to, PHP Foundation?

Editoval jasir (24. 7. 2009 23:41)

Ondřej Brejla

Nápad se sepsáním problémů a jejich řešení k jednotlivým vyjímkám…proč ne, jen mi přijde, že Nette vyjímek je poměrně málo, takže problémů u každé z nich bude hromada. Ale tak v pozdějším debugu to asi třeba někomu může pomoci.

S těmi moderovanými diskusemi pro třídy a metody ?? To se mi moc nezdá…snad jen vybrané třídy (které?), ale metody? Opravdu nevím, proč by metoda getName() z Identity měla mít svou moderovanou diskusi ;-)

jasir

Warden napsal(a):

Nápad se sepsáním problémů a jejich řešení k jednotlivým vyjímkám…proč ne, jen mi přijde, že Nette vyjímek je poměrně málo, takže problémů u každé z nich bude hromada. Ale tak v pozdějším debugu to asi třeba někomu může pomoci.

No, málo jich není, já jsem myslel ke konkrétnímu vyhození vyjímky v konkrétní metodě.
Zkus si grep -E "throw new" -r -n --include=*.php * v Nette adresárí, uvidíš, kde všude a s jakým textem se vyjímka vyhazuje. Každé vyhození v různých třídách a s různým textem popisuje jinou logickou chybu. Udělal jsem si takovou malou analýzu a je odhadem tak 100–120 míst, kde Nette vyhodí vyjímku z různým textem (a různou příčinou chyby)

Mimochodem – všechna čest Davidovi, ty popisky jsou opravdu pěkně napsané.

Bohužel – implementace podobné věci není tak snadná, jak se mi na první pohled zdálo.
Chtělo by to, aby každé takové vyhození mělo nějaký jedinečný identifikátor, což není tak snadné (text vyjímky a pozice ve zdrojovém kódu se může změnit).

Čili bez poměrně rozsáhlého přepsání části Nette (vytvořit seznam všech vyhažováných exceptions jako konstanty a doplnit identifikátor jako code ke každému vyhození: `throw new LogicException*('Invalid ',1003)) to asi nepůjde. Asi smolík.

S těmi moderovanými diskusemi pro třídy a metody ?? To se mi moc nezdá…snad jen vybrané třídy (které?), ale metody? Opravdu nevím, proč by metoda getName() z Identity měla mít svou moderovanou diskusi ;-)

Proč ne? Když se podíváš na manuál k php, jediná věc, kterou na něm opravdu oceňuji jsou právě ty diskuze a tipy pod každou funkcí. Co je na tom špatného? Diskuze bude prázdná (a nezaložená) dokud tam někdo něco nenapíše. Moderátor pak z případné diskuze vyextrahuje to zajímavé a nechá to tam. Api v současné podobě je hodně stručné (1 věta max) a toto by mohlo být snadná cesta jak shromáždit informace na správném místě.

Editoval jasir (26. 7. 2009 14:01)

Ondřej Brejla

Tím málo jsem myslel málo typů, ne že se málo vyhazují ;-) Problém jsem právě viděl v tom jednoznačném rozlišení, jak píšeš.

U php každá ta fce je v podstatě nějakým způsobem samostatně použitelná, resp. nejsou tam fce, které se používají interně. Hromadu fcí z Nette samostatně nepoužiješ, ale používají se třeba interně v nějakém kontextu, automaticky, běžný uživatel se k nim nemusí nikdy dostat. Proto mi přijde zbytečné, řešit všechny fce.

Jako zajímavější by se mi jevilo mít diskuse třeba přímo k celým třídám. U těch by se mohlo diskutovat o jejich používání a případně o nějakých metodách. Imho to už teď je nějakým způsobem možné. Jen nevím, jak je to se zobrazením diskuse u api, tam by to možná chtělo nějaký odkaz na diskusi k dané třídě ve fóru. Co myslíš?

Editoval Warden (26. 7. 2009 16:39)

na1k

Nápad je to určitě dobrý, jenom s tou realizací by to bylo asi trošku složitější .(

Namísto přepisování vyjímek v celém Nette bych to raději řešil tak, že by odkazy vytvářela až Laděnka a to třeba ve tvaru s nějakým ?query= a chyba by se dekódovala až na straně wikiny. (Její jádro neznám, ale určitě je možné ji rozšířit tak, aby takovýto požadavek s chybovou hláškou nějakým mechanismem rozpoznala a přesměrovala na stránku s řešením.)

A co se týče diskusí k třídám, ty bych určitě necpal na fórum, ale jak už řekl Warden, raději do API nebo možná ještě lépe do wiki. U API bych se bál nepřehlednosti, zato wiki mi přijde na popis + ukázky použití a tipy od uživatelů ceklem vhodná.

Ondřej Mirtes

Stačilo by, kdyby každá výjimka dostala své unikátní číslo, pod kterým by byla dohledatelná v dokumentaci (takhle se to v běžných aplikacích dělá), pro pohodlí by přímý odkaz na dokumentaci mohla vytvářet Laděnka.

Jerry123456789

na1k napsal(a):
Namísto přepisování vyjímek v celém Nette bych to raději řešil tak, že by odkazy vytvářela až Laděnka a to třeba ve tvaru s nějakým ?query= a chyba by se dekódovala až na straně wikiny. (Její jádro neznám, ale určitě je možné ji rozšířit tak, aby takovýto požadavek s chybovou hláškou nějakým mechanismem rozpoznala a přesměrovala na stránku s řešením.)

Dobrý nápad, chtělo by to aby si vždy při přidání nové verze do changelogu wikina šáhla do ní, vygeenerovala by si seznam výjimek a podle jejího textu (to by chtělo asi reguláry na proměnné části) by nasměrovala na správnou stránku.

Ale oddělil bych to do např. ErrorDoc

na1k

Jerry123456789, no právě by možná stačilo přesměrovat na tvorbu nové stránky, tak jak to wikina klasicky dělá s neznámými hesly. Šahat do changelogu by bylo myslím zbytečně složité a navíc by to vyžadovalo důsledně všechny chyby do changelogů psát, což téměř odpovídá tomu, že by se všechny v kódu očíslovaly.

Kdyby se navíc vhodně nastavilo oprávnění pro zápis do wiki, mělo by to fungovat dobře. Cílem je minimalizovat zásahy do Nette a následné udržování.

PetrP

Tak už Exception ma v constructoru druhej parametr $code. Takže podle mě se nabízí u vnitřních výjimek přidat code z nějakým nette prefixem (aby se snížila hrozba kolize z nějakejma číslama co případně používám v aplikaci)

InvalidStateException('bla bla bla',2301780001) a pak by už laděnka jen tohle detekovala, a odkázala na stránku https://nette.org/cs/faq/exception/0001

Možná by to nemuseli mít všechny výjimky.

David Grudl

Určitě by to šlo, přes kódy, teď spíš jde o to vytipovat výjimky, u kterých by to bylo užitečné.

PetrP

David Grudl napsal(a):

Určitě by to šlo, přes kódy, teď spíš jde o to vytipovat výjimky, u kterých by to bylo užitečné.

A co to rovnou dát u všech a logovat na nettephp na které kódy lidi chodí, a u těch nejnavštěvovanějších přidat text ;]

Inza

PetrP napsal(a):

David Grudl napsal(a):

Určitě by to šlo, přes kódy, teď spíš jde o to vytipovat výjimky, u kterých by to bylo užitečné.

A co to rovnou dát u všech a logovat na nettephp na které kódy lidi chodí, a u těch nejnavštěvovanějších přidat text ;]

To je moc dobrý nápad…

jasir

PetrP napsal(a):

David Grudl napsal(a):

Určitě by to šlo, přes kódy, teď spíš jde o to vytipovat výjimky, u kterých by to bylo užitečné.

A co to rovnou dát u všech a logovat na nettephp na které kódy lidi chodí, a u těch nejnavštěvovanějších přidat text ;]

V tuto chvíli se jedná a cca 65 vyhození vyjímek v Nette, asi by bylo opravdu nejsnazší očíslovat všechny. Otázka je, jaký zvolit způsob číslování. Napadají mě tyto možnosti:

číslovat je bez zvláštního smyslu, prostě sekvenčně od 1 nahoru
pro každý soubor který může vyhodit vyjímku zavést vlastní číselný prostor, tedy například Annotations.php by měla čísla od 100–199, Component.php od 200–299 apodobně. K čemu je to dobré? Když David/Roman/Jakub/… edituje nějaký soubor a chce vyhodit novou vyjímku, podívá se jen do hlavičky souboru které je další číslo vyjímky pro daný soubor a nemusí dohledávat „další globální volné číslo vyjímky“.

Editoval jasir (17. 8. 2009 12:56)

kravčo

jasir napsal(a):

V tuto chvíli se jedná a cca 65 vyhození vyjímek v Nette, asi by bylo opravdu nejsnazší očíslovat všechny.

Mne grep našiel 267 vyhodení…

Otázka je, jaký zvolit způsob číslování.

Mne osobne sa číslovanie nepáči, hlavne preto, že má veľký wtf faktor a nezdá sa mi dobre udržiavateľné.

Dostal som nápad, ktorý mi príde lepší a vôbec nešpatí kód. Každú výnimku (ku ktorej chcem na bluescreene odkaz do dokumentácie) opatríme komentárom známim napr. z dibi driverov:

// ...

if (something_went_wrong()) {
    // @see https://doc.nette.org/exceptions/config/adapters
    throw new /*\*/Exception("Something went wrong.");
}

// ...

Dôležité je, že výnimka má namespace (v príklade „config/adapters“), v ktorom sa môže nachádzať dokumentácia jedného či viacerých vyhodení, podľa toho ako sa to hodí. Forma odkazu môže byť iná, napr. vo forme URI nette-doc:exception/config/adapters, ale práve komentár s http odkazom má správnu funkciu, že je jasný a použiteľný i pre ľudí, ktorí čítajú zdrojáky.

site("nette.org").routers++;

Ad-hoc implementácia v bluescreen.phtml je naozaj jednoduchá:

function _netteDebugDocLink($e)
{
    $lines = file($e->getFile());
    if (isset($lines[$e->getLine() - 2])) {
        if (preg_match('#\s*//\s+@see (.*)#', $lines[$e->getLine() - 2], $m)) {
            echo "<p>See <a href=\"$m[1]\">exception documentation</a> for more information.</p>\n";
        }
    }
}

jasir

kravco napsal(a):

jasir napsal(a):
V tuto chvíli se jedná a cca 65 vyhození vyjímek v Nette, asi by bylo opravdu nejsnazší očíslovat všechny.

Mne grep našiel 267 vyhodení…

Ano, omlouvám se. Opomenuté -r :-(

kravco to vyresil:

Výborné, jednoduché, přehledné. Že mě to nenapadlo ;-)

Editoval jasir (17. 8. 2009 16:13)

redhead

taky se mi libí kravcovo řešení. Sakra, do distribuce s tím!! ;)

David Grudl

Trošku mi to připadá, že se rozumné řešení nahrazuje za brute force ;)

Ve frameworku se vyhazují dva druhy výjimek – jedny jsou určeny k zachycení a zpracování, ty druhé k „zabití“ aplikace (prostě fatal error). Dají se odlišit i tím, že první případ patří do jmenného prostoru Nette, druhý do prostoru globálního (SPL výjimky a jejich potomci v souboru exceptions.php).

Nás bude zajímat ta druhá kategorie. Zde se hodně snažím o to, aby každá výjimka generovala dostatečně vysvětlující text. Celá řada těchto výjimek nepotřebuje další vysvětlování. Pokud se snažím vytvořit instanci třídy Environment a napíše mi to Cannot instantiate static class Environment tak není moc co dodávat.

Problém nastává jen při určitých konkrétních scénářích. Typický příklad: vytvoření formuláře v metodě render a výjimka The signal receiver component myForm is not found. Zde totiž není patrná přímá souvislost a pokud se to stane programátorovi poprvé, vysvětelní by jistě ocenil. Nicméně nemá smysl číslovat všechny výjimky, ale naopak podchytit tyto scénáře. Jim odpovídajících výjimek nebude mnoho a lze jim přiřadit kódy. Nebo si vystačit s textem a na webu mít tabulku masek jako BadSignalException: The signal receiver component %%s is not found a příslušných stránek. Nehledě na to, že je otázka, jestli programátoři budou na nějaký link klikat, jestli nejsou spíš zvyklí nastartovat Google a dát tam text té výjimky.

jasir

Kravčovo řešení přeci umožnuje snadno vybrat takové scénáře o kterých mluvíš a je krásně inobtrusive…

Co se týče jestli budou klikat či ne – měli by. Já bych kliknul. Je to pohodlnější než jít prolézat fórum a pak se znovu ptát na to, co x lidí před nimi. Nejde také jen o to, jestli kliknou nebo ne, ale aby se postupně shromáždili informace k typickým problémům na jednom přehledném místě.

kravčo

David Grudl napsal(a):

Ve frameworku se vyhazují dva druhy výjimek – jedny jsou určeny k zachycení a zpracování, ty druhé k „zabití“ aplikace (prostě fatal error). Dají se odlišit i tím, že první případ patří do jmenného prostoru Nette, druhý do prostoru globálního (SPL výjimky a jejich potomci v souboru exceptions.php).

Nás bude zajímat ta druhá kategorie.

Nad tým, či má zmysel dokumentovať vyhodenia výnimiek Nette (príkladom môže byť AuthenticationException), som rozmýšľal a prišiel som na to, že ako kedy. Práve ladenku s kričiacou AuthenticationException môže začiatočník považovať za chybu frameworku, nie za jeho (sebou zavinené) zlé použitie.

Zde se hodně snažím o to, aby každá výjimka generovala dostatečně vysvětlující text. Celá řada těchto výjimek nepotřebuje další vysvětlování. Pokud se snažím vytvořit instanci třídy Environment a napíše mi to Cannot instantiate static class Environment tak není moc co dodávat.

Jedným z rysov mnou navrhoveného prístupu je, že je voliteľný. Výnimky, ktoré bližší popis nepotrebujú, popisný komentár mať nemusia (odkaz sa v takom prípade nezobrazí). Navyše im kedykoľvek v budúcnosti môže (bez ďalšieho zásahu) pribudnúť.

Nehledě na to, že je otázka, jestli programátoři budou na nějaký link klikat, jestli nejsou spíš zvyklí nastartovat Google a dát tam text té výjimky.

To asi zistíme len tak, že sa tento princíp zavedie a štatistiky nám dajú odpoveď… Možno by mohol pribudnúť i odkaz na google ;)

Exception

Something went wrong.

Learn what may this mean in Nette documentation.
Just fucking google it!

jasir napsal(a):

Nejde také jen o to, jestli kliknou nebo ne, ale aby se postupně shromáždili informace k typickým problémům na jednom přehledném místě.

Presne.

mejla

Také se přimlouvám za link na dokumentaci řešení problému + možná best practice řešení ? :-) Teď na začátku by mi to moc pomohlo při té „strmější křivce učení“ ;-)

jasir

Založil jsem wiki stránku, kde se pokusím postupně identifikovat podle dotazů na fóru kandidáty na rozšířenou informaci. Jste samozřejmě více než vítáni k participaci.

Snad to bude ku prospěchu – nežli se rozhodne zda to stojí za implementaci a jak má taková implementace vypadat.

Mě osobně se kravčův nápad pomocí anotací @see líbí moc.

redhead

Dávám rozhodně ruku nahoru za tuhle featuru a kravčovo řešení!

Patrik Votoček

jasir napsal(a):

Mě osobně se kravčův nápad pomocí anotací @see líbí moc.

redhead napsal(a):

Dávám rozhodně ruku nahoru za tuhle featuru a kravčovo řešení!

Anotace jsou COOL ale jenom do doby kdy příjde nováček se zapnutým eAcceleratorem.

jasir

vrtak-cz napsal(a):

jasir napsal(a):

Mě osobně se kravčův nápad pomocí anotací @see líbí moc.

redhead napsal(a):

Dávám rozhodně ruku nahoru za tuhle featuru a kravčovo řešení!

Anotace jsou COOL ale jenom do doby kdy příjde nováček se zapnutým eAcceleratorem.

Při developmentu kdy je zapnutá laděnka moc eAccelerator asi nebývá zapnutý.

David Grudl

Tohle zrovna nevadí, protože anotace se budou získavat jinak, než přes phpDoc. (prostě otevřením souboru a načtení řádky).

Cifro

Ad eAccelerator: nedávno som sa popalil na eAcceleratore. Ale aspoň som zistil, že dá sa prepnuť aby neodstraňoval komentáre z kódu. Ale to je už na hostingu.

http://eaccelerator.net/ticket/229

...run configure with the --with-eaccelerator-doc-comment-inclusion switch...

Edit: // pridal som link, na post vo fóre kde som to riešil

Editoval Cifro (2. 9. 2009 13:02)

jasir

Cifro napsal:

Tohle je dost zajímavá informace! Pokud se dá testovat nastavení eAcceleratoru z Php, bylo by dobré to zařadit do Requirements Checkeru.

Patrik Votoček

Neověřuje tohle Requirements Checker pomocí X redirectů kde by se mělo odstranění komentářu eAcceleratorem projevit? (Pokud se neprojevi jako by na serveru eAccelerator nebyl). Edit: tzn „už to tam je“. (myslím)

Editoval vrtak-cz (2. 9. 2009 12:47)

jasir

Máš pravdu, ověřuje se to.