Na navigaci | Klávesové zkratky

Translate to English… Ins Deutsche übersetzen…

Který framework má nejlepší dokumentaci?

Zajímalo mě, který PHP framework má nejlepší dokumentaci. A jak si v žebříčku stojí Nette. Jenže jak to zjistit?

Všichni víme, že nejhorší je žádná dokumentace. Pak následuje nedostatečná dokumentace. Opakem je obsáhlá dokumentace. Tedy zdá se, že podstatným vodítkem je samotný objem dokumentace. Pochopitelně obrovskou roli hraje i srozumitelnost a aktuálnost, dojem dělá čtivost a bezchybnost. Tyto faktory se velmi těžko měří. Nicméně sám vím, kolik částí dokumentace Nette jsem mnohokrát přepsal, aby byly jasné, kolik oprav jsem mergoval, a předpokládám, že se tak děje u každého letitého frameworku. Že tedy postupně všechny dokumentace konvergují k podobné kvalitě. Tudíž si jako vodítko dovolím brát čistě objem dat.

Pochopitelně se objem dokumentace musí dát do poměru s velikostí té které knihovny. Některé jsou i řádově větší než jiné a pak by měly mít i řádově větší dokumentaci. Nejjednodušší je velikost knihovny stanovit podle objemu PHP kódu. S normalizovaným bílým místem, bez komentářů.

Vytvořil jsem graf poměru anglické dokumentace ku kódu u známých frameworků CakePHP (3.8), CodeIgniter (3.1), Laravel (5.8), Nette (3.0), Symfony (4.4), YII (2.0) a Zend Framework (2.x):

Jak z grafu vidíte, obsáhlost dokumentace vůči kódu je u všech frameworků velmi podobná.

Vyčnívá CodeIgniter, což je dáno i tím, že jde o opravdu malý framework. Smekám před CakePHP a YII, které se snaží udržovat dokumentaci v celé řadě dalších jazyků. Obsáhlost dokumentace Nette je takřka stejná, jako v případě Symfony nebo Zend Frameworku. Nette je jediný framework, který má 1:1 překlad i v naší mateřštině.

Doslov: smyslem grafu není ukázat, že jeden sloupeček je o trošku vyšší nebo nižší než druhý. Při jiné normalizaci by se poměry změnily, metrika je primitivní. Smyslem je vyvrátit mýtus, že Nette má chabou dokumentaci. Samozřejmě, že dokumentace by mohla být (a bude!) mnohem obsáhlejší, určitě tam spousta věcí chybí, ale úplně stejně je tomu u všech ostatních frameworků. Když někde čtu, jak je dokumentace špatná, a pisatele se zeptám, co přesně mu chybělo, abych to mohl doplnit, obvykle z odpovědi uteče, že mnoho let dokumentaci neviděl a vlastně neví. Naopak při osobním setkání nebo emailem mi řada programátorů dokumentaci Nette pochválila, že jim připadá skvělá. Tento graf jsem vytvořil hlavně pro sebe, abych získal náhled na skutečnost.


phpFashion © 2004, 2019 David Grudl | o blogu

Ukázky zdrojových kódů smíte používat s uvedením autora a URL tohoto webu bez dalších omezení.