JavaDoc tipy & triky
Každý se s tím zajisté již mnohokrát setkal. Pročítat si cizí kód a dokonce i vlastní bývá velice obtížné. Nikdy nevíme co se programátorům honilo hlavou, když psali zrovna takovou podmínku. Co je vedlo k tomu, že je cyklus omezený právě takhle? Spousty podobných otázek si kladl každý z nás. Já sám jsem se v takové situaci ocitl přesně ve chvíli, kdy jsem se stal novým členem týmu BCVsolutions s.r.o. Již v prvních dnech jsem si musel pročítat stovky řádků kódu a ještě rozsáhlejší dokumentaci.
Veškeré publikace, doporučení a další poznámky ohledně dokumentace by vydaly na nespočet mrtvých stromů. Nechci tady na tuto hromadu přidávat nic dalšího a rád bych spíše uvedl něco, u čeho by se programátor zastavil a řekl si, že by to mohl použít pro vylepšení dokumentace své práce.
Tag @inheritDoc
První věcí, která programátorům pomůže je tag s názvem @inheritDoc. V případě, že překrýváme metodu ze supertřídy docílíme tímto tagem toho, že se popis metody vytvoří podle překryté metody. Mám-li překrývanou metodu foo(); s komentářem „Naprosto dokonalá metoda“, překryjeme jí jinou metodou foo(); a vložíme do komentáře tag @inheritDoc docílíme toho, že i tato metoda má komentář „Naprosto dokonalá metoda“. Ušetříme si tak nemalé množství zbytečně se opakujícího textu.
Tag @see a generický datový typ
Neušetřím si zde malou poznámku k tagu @see a odkazování na generický typ. Představme si, že máme metodu foo(List<boo> param);. Sám jsem chvíli bádal nad tím, jak se odkazovat na takovou metodu. Překvapivě existují dva způsoby: #foo(List) anebo #foo(object). Tedy bez udání typu Listu a nebo uvedením předka. Je dobré si uvědomit, že kterýkoliv parametr v odkazu můžeme nahradit i předkem onoho parametru.
Obrázky v dokumentaci? Žádný problém!
Vkládání obrázků do dokumentace pomocí JavaDoc je jednou z věcí, kde si člověk přínos uvědomí velice těžko. Stačí si ale představit složitý, přesto nedělitelný, algoritmus, který je naprogramován v jedné metodě. Slovní popis je v takovou chvíli hodně nedostatečný. Přidáme-li k tomu možnou jazykovou bariéru je grafické znázornění algoritmu velice výhodné. Když jsem hledal možnosti vložení obrázků, našel jsem jedno velice rozšířené řešení. Vložit ho jako HTML tag a obrázek kódovat jako Base64 data. Takové řešení je ale naprosto proti duchu dokumentace, která by měla být přehledná i ve zdrojovém kódu, což těžko dodržíme, pokud do něj vložíme Base64 data. Přesto existuje jedna cesta, jak dostat obrázky do dokumentace pohodlně. Stačí obrázek zkopírovat do adresáře „doc-files“ vedle zdrojového kódu. Máme tedy následující strukturu projektu:
../src/project/my_class.java – zdrojový kód, kde se odkazujeme na obrázek
../src/project/doc-files/image-1.jpg – obrázek k danému komentáři
Poté už stačí vložit do komentáře v my_class.java následující kód:
<code> <img src="doc-files/image-1.jpg"> </code>
Tímto máme v dokumentaci i obrázek, který jsme chtěli.
Tento článek není žádnou rozsáhlou dokumentací JavaDocu, nýbrž pouze obsahuje problémy a věci, na které jsem narazil a nenašel vhodné řešení či vysvětlení. Doufám, že vám tento článek pomohl při tvorbě lepší a přehlednější dokumentace. Pokud byste měli jakýkoliv dotaz, neváhejte mne kontaktovat na jan.effenberger@bcvsolutions.eu.
