JavaDoc nedostatky

V poslední době často pracuji s cizím kódem a je to opravdu zázrak narazit na kvalitně napsaný a okomentovaný kód. Největší problém komentářů je ten, že buď vůbec nejsou a nebo jsou, ale jen papouškují to, co je hned zřejmé ze samotného kódu. O přínosu komentování jsem již psal, dnes bych rád uvedl několik nedostatků v JavaDoc komentářích, na které jsem měl možnost narazit (malá poznámka pro upřesnění - i když často používám slovíčko komentáře, tak v tomto článku dále vždy myslím JavaDoc komentáře, ne komentáře přímo v kódu):

• míchání češtiny (někdy i s diakritikou) a angličtiny - dříve jsem preferoval pouze angličtinu pro psaní komentářů, ta čeština mi tam prostě neseděla. Dnes jsem spíše pro používání češtiny z těchto důvodů: čeština vždy bude pro nás čitelnější než jakýkoliv jiný jazyk a i psaní komentářů je jednodušší, větší přínos z pohledu poskytované informace. Osobně s angličtinou nemám problém, ale sám jsem zjistil, že v češtině jsem schopen se vyjádřit o dost lépe. Dělám nyní většinou na interních projektech bez zahraničních kolegů, takže není problém s mateřským jazykem. Každopádně když už, tak zvolit jeden jazyk, aby to nevypadalo jako na jednom projektu, kde bylo možné narazit na české, slovenské, anglické a dokonce německé komentáře.
  
  
• zvýraznění první věty komentáře - První věta komentáře má větší význam oproti dalším větám - jednak je to první informace, kterou uživatel čte a jednak je používaná pro stručný popis v přehledu metod. První věta (z pohledu JavaDoc nástroje) končí tečkou, kterou následuje mezera, tabulátor, znak konce řádku a nebo první blokový tag. Takto tedy ne:
  

  
     /**
       * <p>
       * If is set, it use special ScrollableResultsDecorator, that enable or
       * disable to add object in final list
       * </p>
       * <h4>NOTE:</h4>
       * <p>
       * Also, it respects the total count of entries that overlap your paged
       * list.
       * </p>
       */

  
  
  
• @author tag u metod - používat @author tag u metod nemá žádný význam, protože to JavaDoc nástroj nepodporuje.
  
  
• nepopisovat to, co za nás udělá JavaDoc automaticky - Je zbytečné kopírovat komentáře z metod rozhraní do implementace, je zbytečné uvádět implementující třídy rozhraní atd. JavaDoc nástroj má algoritmus na kopírování komentářů z nadřazených tříd a na rozdíl od verze 1.3 se vždy nekopíruje celý JavaDoc komentář (buď celý nebo nic), ale třeba i jen jeho části jako @param, @throws a @return. Někdo to sice nekopíruje, ale používá @inheritDoc a @see, ale to nejsou srovnatelné alternativy. Např. při použití @inheritDoc se kopíruje jen určitá část celého JavaDoc komentáře a tag @see má zcela odlišnou sémantiku. @inheritDoc je vhodné používat, pokud chci rozšířit určitou část dokumentace nadřazené třídy nebo metody.
  
  
• zdokumentovat synchronized a native modifikátory - V JavaDoc API nenajdete informace o tom, zda je metoda synchronizovaná nebo ne (je to implementační záležitost). Proto je nutné tuto informaci uvést v JavaDoc.
  
  
• zbytečně neopakovat význam tagů - Zde mám na mysli toto "@return Returns the statementBuilder." Proč psát 2x, že metoda vrací statementBuilder?
  
  
• místo názvů tříd a metod používat odkazy @link - Hodně často se v komentářích odkazujeme na jiné třídy nebo metody a o dost větší přidaná hodnota bude, když si uživatel mezi jednotlivými komentáři může překlikávat, než aby to musel manuálně hledat. Proto je vhodné používat tagy @link resp. @linkplain.
  
  
• používat @literal nebo @code pro psaní s <> - S příchodem Javy 5 a možností parametrizace může být problém zápisu těchto konstrukcí do JavaDoc komentářů. To stejné platí i o HTML a XML kódu. Než používat &lt; &gt; jako náhradu za <>, tak je lepší použít tagy @literal nebo @code. Tím se výrazně zvýší čitelnost JavaDoc i bez nutnosti zpracování JavaDoc nástrojem. Bohužel tyto tagy nelze použít na víceřádkové ukázky kódu, kde nám jde o přesné zarovnání kódu. Snad v příští verzi, pořád je tedy (bohužel) nutné používat tento způsob:
  

  
   * <p>Ukazka konfigurace ve web.xml:
   * <pre>
      &lt;listener&gt;
          &lt;listener-class&gt;com.o2bs.globals.web.common.envconfig.EnvAwareLog4jConfigListener&lt;/listener-class&gt;
      &lt;/listener&gt;
   * </pre>

  
  
  
• psát přehledné komentáře i bez nutnosti použití JavaDoc nástroje - Hodně lidí hledí zejména na výslednou HTML podobu JavaDoc komentářů a ne na to, jak to vypadá přímo v Java kódu. Je pravda, že výsledná HTML podoba je asi nejdůležitější, ale dost často se prochází čistý Java kód bez IDE (a nebo i v IDE je rychlejší číst JavaDoc bez nutnosti si je zobrazovat v HTML podobě) a pak se i ocení, když to vypadá pěkně bez JavaDoc nástroje. Dle mého názoru se nemá cenu snažit o správně formátované HTML (tedy používání ukončovacích tagů), protože JavaDoc nástroj generuje HTML ve verzi 3.2 (i když hlavičku stránek dává pro HTML 4.0).
  

Psát správné (krátké, jasné s vypovídající hodnotou) JavaDoc komentáře není vůbec jednoduché a sám se občas nachytám, když se po nějakém čase vracím ke svému kódu. Pro ty, kdo chtějí JavaDoc dotáhnout k dokonalosti, doporučuji referenční příručku k JavaDoc nástroji a dokument s popisem konvence psaní komentářů.