Java/Javadoc

Je dobré dokumentovat kód, který napíšeme. Někdy kód uložíme k ledu a třeba po roce si vzpomeneme, že tam něco ještě potřebujeme dodělat nebo změnit. Tou dobou už jsme zapomněli který kus kódu je k čemu dobrý. Bez dokumentace budeme určitě nějakou dobu tápat a zjišťovat co je vlastně co...

Odstrašující příklad:

public class Sv {
     Id di;

     public String gt(String p) {
       //...
     }
 
     public Id gi(String r) {
       //...
     }
 
     public int gbs() {
       //...
     }
 }

Kdo se v tom má sakra vyznat? :-D

V Javě lze k tomuto účelu použít nástroj javadoc

Nejlépe si lze jeho použití ukázat na příkladu:

/**
  Toto je komentář javadoc.
  Od obyčejného komentáře se liší tím, že začíná dvěma hvězdičkami.
 
  Zde je popis třídy Server.
  Javadoc komentáře se píšou vždy těsně před třídu,
  kterou chceme dokumentovat (třída, proměnná, metoda...)
  V Javadoc komentářích můžeme používat <b>HTML značky</b>
  */
 public class Server {
    /*
     Obyčejné komentáře
     (ty co začínají jen jednou hvězdičkou)
     javadoc ignoruje
    */
 
    /** Zde je popis proměnné defaultIdentity */
    Id defaultIdentity;
 
 
    /**
     Zde je popis metody generateResponse.
     Javadoc komentář může kromě "obyčejného" popisu
     obsahovat i speciální příkazy uvozené zavináčem.
     Příkaz "param" je popis parametru,
     příkaz "return" je popis návratové hodnoty, jak je vidět níže.
 
     @param parameters Toto je popis parametru "parameters"
     @return Zde je popis toho, co funkce vrací
    */
    public String generateResponse (String parameters[]) {
       //...
    }
 
    /**
     Zde je popis metody getIdentity
     @param remoteHostName Popis parametru remoteHostName
     @return Zde je popis toho, co funkce vrací
    */
    public Identity getIdentity (String remoteHostName) {
       //...
    }
 
    /**
     Zde bude popis funkce getBytesServed
     @return počet upečených znaků (třeba :)
    */
    public int getBytesServed() {
       //...
    }
 }

Docela rozdíl od toho prvního příkladu, ne? Pokud máme takto přehledně zdokumentované zdrojové kódy, můžeme z nich vygenerovat dokumentaci:

javadoc *.java -d dokumentace

Tento příkaz projde všechny soubory *.java a do adresáře dokumentace z nich vygeneruje dokumentaci.

Pravidlo, že kód se má dokumentovat platí i pro ostatní jazyky. Ve většině funguje princip stejně, nebo podobně, jako v javadocu (Např. doxygen nebo CppDoc pro C++, PHPDoc pro PHP, atd...)