Dokumentace tříd

Tomáš Pitner, Radek Ošlejšek, Marek Šabo, Jakub Čecháček pitner@muni.cz

Typy komentářů

  • řádkové - od značky // do konce řádku, nepromítnou se do dokumentace

     // inline comment, no javadoc generated

  • blokové - mohou být na libovolném počtu řádků, nepromítnou se do dokumentace

    /* block comment, no javadoc generated */

  • dokumentační - strukturované, libovolný počet řádků, promítnou se do dokumentace

    /** documentary comment, javadoc generated */

Dokumentace kódu uvnitř metod

  • Řádkové nebo blokové komentáře vysvětlující smysl kódu.

  • Jsou vidět pouze při detailním studiu zdrojového kódu metody.

  • Pokud váš kód vyžaduje vysvětlující komentář, je něco špatně. Refaktorujte kód do čitelnější podoby a/nebo rozdělte metodu na menší metody (s private nebo protected viditelností).

Dokumentace metod

  • Definuje kontrakt pro použití metody, tj. vysvětluje význam a omezení vstupních argumentů a výstupních hodnot, chování metody apod.

  • Veřejné metody, včetně konstruktorů, je nutné poctivě popsat dokumentačními komentáři, aby bylo použití metod jasné bez nutnosti studia zdrojového kódu.

  • U neveřejných metod není strukturovaná dokumentace tak kritická, protože se používají převážně pouze v rámci dané třídy (případně podtříd). Při správném (popisném) pojmenování metod a parametrů tak nemusí být dokumentace nutná. Nicméně se rovněž doporučuje.

  • Gettery a settery se nemusí dokumentovat, protože jejich význam je zcela jasný.

Dokumentace atributů

  • Atributy jsou důležité datové položky, kterou souvisí stavem a životním cyklem objektu. A to i přesto, že jsou většinou privátní.Jejich dokumentace je proto velmi žádoucí.

  • Atributy které ovlivňují použití nebo chování objektu by měly být popsány strukturovanými dokumentačními komentáři. Ostatní stačí řádkovými nebo blokovými.

Dokumentace třídy

  • Účel každé třídy by měl být jasně popsán strukturovanými dokumentačními komentáři, aby bylo zřejmé její použití bez nutnosti studovat konkrétní metody nebo atributy.

Strukturovaná dokumentace javadoc

  • Slouží ke strojovému generování dokumentace z dokumentačních komentářů, ale i ze samotné struktury programu.

  • Dokumentace se vygeneruje do sady HTML souborů, takže to bude vypadat jako v Java Core API.

  • Používá speciální značky se znakem zavináč, např. @author, v dokumentačních komentářích = Lze dokumentovat i celý balík a to sepsáním souboru package-info.html v příslušném balíku.

JavaDoc třídy

/**
 * This class represents a point in two dimensional space.
 *
 * @author Petr Novotny
 * @author Karel Ctvrty
 **/
 public class Vertex2D { ... }

Komentář metody I

  • Zkrácený oficiální komentář metody toString():

/**
 * Returns a string representation of the object. In general, the
 * {@code toString} method returns a string that
 * "textually represents" this object. The result should ...
 *
 * @return  a string representation of the object.
 */
 public String toString() { ... }

  • Část {@code toString} značí formátování, vypíše to toString neproporcionálním písmem.

Komentář metody II

/**
 * Returns the smaller of two int values.
 * If the arguments have the same value, the result is that same value.
 *
 * @param   a   an argument.
 * @param   b   another argument.
 * @return  the smaller of {@code a} and {@code b}.
 */
public int min(int a, int b) {
    return (a <= b) ? a : b;
}

Kde uvádíme dokumentační komentáře

  • Dokumentační komentáře uvádíme:

    • Nad hlavičkou třídy — pak komentuje třídu jako celek.

    • Nad hlavičkou metody — pak komentuje příslušnou metodu.

    • Nad deklarací atributu — pak komentuje příslušný atribut.

  • Doporučení Sun/Oracle k psaní dokumentačních komentářů — How to Write Doc Comments for the Javadoc Tool