DagblogUmění jménem JavaDoc
Čas od času zabrousím do API dokumentace Spring frameworku, abych se něco přiučil z umění jménem tvorba dokumentace k API. Protože ať chceme nebo ne, je rozdíl psát JavaDoc a jJavaDoc. Hodně JavaDocu, který jsem napsal nebo jsem viděl sklouzávalo k tomu, aby popsalo to co má čtenář přímo před nosem. Jenže postupem času jsem přišel na to, že správný JavaDoc musí obsahovat informace, které by musel jinak čtenář hledat mezi řádky kódu.
Mezi řádky kódu se typicky hledá:
- jakým způsobem daný objekt získat
- jak jej zkonfigurovat
- jaké ma dependence
- jak lze chování modifikovat
- jaký je vztah k ostatním entitám
Oceňuji pokud JavaDoc obsahuje link na externí informace, které pomohou pochopit implementační detail a nebo zvolený přístup. K nezaplacení jsou i příklady jak dané API použít. Samozřejmě psát takto detailní JavaDoc je práce v pravdě puntičkářská a ještě složitější bývá udržet JavaDoc aktuální se všemi změnami, kterými API projde.
Spíše pro zábavu zkuste náhodně otevřít deset tříd z projektu, na kterém právě pracujete, a bodově ohodnoťte od 0-10 v jakém stavu je jejich JavaDoc podle následujících kritérií :
- Třída nemá JavaDoc (0 bodů)
- JavaDoc třídy je zastaralý či zavádějící
- Javadoc třídy je velice stručný
- Z JavaDocu třídy i nezasvěcený člověk pochopí k čemu třída slouží
- JavaDoc třídy přidává i další informace nad rámec (10 bodů)
Výsledky:
- 0-20 bodů - vytváříte pravděpodobně samodokumentující se kód
- 21-40 bodů- kromě samodokumentujícího kódu tu a tam utrousíte v dokumentaci i nějakou irelevantní poznámku
- 41-60 bodů - snaha vytvořit nějakou dokumentaci je patrná. Třídu jsou alespoň nějak dokumentované.
- 61-80 bodů - o JavaDocu vašich tříd lze prohlásit snese přísnějších kritérií
- 81-100 bodů - gratuluji, zdá se, že jste dosáhli dokumentačního nebe
