Návod -> Komentáre v zdrojovom kóde

Hlavný účel komentárov v zdrojovom kóde je uľahčiť pochopenie daného zdrojového kódu. Najdôležitejšia vec pri písaní komentárov je, aby sa písali do vopred definovaných blokov. Potom sa môže z takýchto komentárov vygenerovať dokumentácia pomocou nástrojov ako Javadoc alebo Doxygen (ukážka - https://svn.cnl.tuke.sk/monica/BasicMeter/Releases/DP2011/JXColl.pekar/src/sk/tuke/cnl/bm/JXColl/IPFIX/FieldSpecifier.java). Keď vývojár komentuje zdrojový text, ktorý vytvoril, drží sa nasledujúcich pravidiel:

• Na začiatku sa vytvorí väčší blok komentára. Ten obsahuje licenciu, autora a opis softvéru, ktorého je daná trieda časťou.

/* 
* Copyright (C) "ROK" "MENO AUTORA"
*
* This file is part of JXColl.
*
* "NAZOV KOMPONENTU" is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published 
* by the Free Software Foundation; either version 3 of the License, 
* or(at your option) any later version.
*
* "NAZOV KOMPONENTU" is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with "NAZOV KOMPONENTU"; If not, see <http://www.gnu.org/licenses/>.
*/

• Nasleduje komentár s opisom triedy a menom autora. Trieda sa komentuje ako jeden celok.
• Komentuje sa každá funkcia, metóda, premenná a konštruktor.
• Komentuje sa stručne. Dôraz sa kladie na vystihnutie významu komentovanej položky.
• Pri komentovaní premennej sa opisuje, ako sa s ňou pracuje.
• Pri komentovaní sa používajú značky, ktoré sú opísané nižšie.
• Komentuje sa vždy v tretej osobe.
• Komentujú sa všetky známe, ale aj neznáme výnimky.
• Pri komentovaní sa nepoužívajú skratky.
• Pri komentovaní tried, premenných a rozhraní sa vynecháva podmet vety. Čiže sa zbytočne neopakujú tie isté slová ako napríklad “Táto trieda ...“.
• Komentáre funkcií a metód sa začínajú slovesom.
• Viacerí autori sa v komentári napíšu v chronologickom poradí.
• Viacero výnimiek v jednom komentári sa zoradia podľa abecedy.
• Parametre sa zoraďujú v takom poradí, v akom boli deklarované.
• Viacero @see značiek sa zoraďujú postupne podľa hierarchie položiek, od najbližšej po najvzdialenejšiu. Čiže od premennej, konštruktor, funkciu, metódu, triedu, po balíček.

Javadoc

Javadoc je nástroj na generovanie dokumentácie vytvorený spoločnosťou Sun Microsystems. Dokumentácia sa generuje vo formáte HTML zo zdrojových textov jazyka Java. Formát komentárov je definovaný v štandardoch pre dokumentovanie Java tried. Niektoré vývojové prostredia, ako sú NetBeans a Eclipse, automaticky generujú HTML dokumentáciu.

Komentáre v Javadoc sa píšu do vnútra značiek

/** 
* ...komentár...
*/

Tým sa zabezpečí, že komentáre budú oddelené od zdrojového kódu. Prvý odsek komentára stručne opisuje danú triedu alebo metódu. Pri komentovaní sa používajú presne definované značky:

• @author – meno autora
• @version – verzia záznamu, maximálne jedna pre triedu a rozhranie
• @param – opisuje parametre konštruktorov, metód alebo funkcií
• @return – opisuje návratovú hodnotu
• @exception/@throw – opisuje výnimku, ktorá môže byť vyvolaná z metódy
• @see – obsahuje odkaz na príbuzné položky
• @since – opisuje verziu Java platformy, od ktorej je daná položka pridaná
• @deprecated – opisuje zastaranú metódu

Existujú dva druhy Javadoc komentárov: komentáre na úrovni triedy a komentáre na úrovni častí. Komentáre na úrovni triedy opisujú triedu ako celok. Sú umiestnené priamo nad kódom, ktorý deklaruje triedu. Tento odsek všeobecne obsahuje značku @author. Komentáre na úrovni častí opisujú funkcie, metódy a konštruktory. Píšu sa nad časťou kódu, ktorý opisujú. Zvyčajne obsahujú značky ako @param, @return.

Vo vývojovom prostredí NetBeans sa Javadoc vygeneruje kliknutím na položku Run na paneli nástrojov a následne zvolením možnosti Generate Javadoc. Kompletnosť vytvorenej dokumentácie sa môže overiť zvolením možnosti Analyze Javadoc, ktorá sa nachádza v záložke Tools. Takto sa vypíšu všetky chýbajúce značky v komentároch, ktoré je potrebné doplniť.

Vývojové prostredie Eclipse generuje Javadoc komentáre zakaždým, keď je vytvorená trieda, metóda alebo konštruktor. Deje sa to pomocou šablón, ktoré sú integrované do prostredia. Tieto šablóny sa dajú upraviť, aby sa Javadoc vytváral v požadovanej forme. Šablóny sa nachádzajú v ponuke Windows > Preferences > Java > Code Style > Code Templates. Tu sa tiež nachádza zaškrtávacie políčko “Automatically add comments for new methods and types“, ktoré je zaškrtnuté. Kliknutím na dané políčko sa Javadoc komentáre prestanú automaticky generovať. Vytvorené komentáre sa môžu konfigurovať po kliknutí na položku Comments, vyberie sa typ komentára a následne sa vyberie možnosť Edit. Text označený značkou ${} je variabilný. Kliknutím na tlačidlo “Insert Variable“ sa zobrazí zoznam možností, ktoré sú k dispozícii pre vloženie.

V prostredí Eclipse sa HTML dokumentácia vygeneruje nasledovným postupom. Pravým tlačidlom sa klikne na projekt a zvolí sa položka Export. Ďalej sa zvolí Javadoc a potvrdí sa tlačidlom Next. Vyberú sa typy, pre ktoré sa Javadoc vytvorí. Zaškrtne sa políčko “Use Standard Doclet“ a určí sa cieľový adresár, do ktorého sa uloží dokumentácia. Kliknutím tlačidla Finish sa ukončí tento proces. Využívaný príkaz Javadoc musí odkazovať na nástroj javadoc.exe, ktorý je poskytovaný JDK.

Doxygen

Doxygen je nástroj, ktorý slúži na generovanie dokumentácie zo zdrojových kódov jazykov C, C++, C#, Fortran, PHP, Python a ďalších. Využíva odkazy dokumentácie na zdrojové kódy, takže čitateľ dokumentu si ľahko môže prezrieť aj zdrojové texty. Podobne ako Javadoc aj Doxygen generuje dokumentáciu vo formáte HTML, ale taktiež aj v RTF, PDF, PS, LaTex , komprimované HTML, alebo ako manuálové stránky. Možných značiek, do ktorých sa vkladajú komentáre, je veľké množstvo. Najčastejšie sa používa rovnaký štýl ako pri nástroji Javadoc, alebo:

/*! 
* ...komentár...
*/

V prvom riadku je komentár so stručným opisom, ktorý prípadne môže pokračovať v druhom riadku. Nasleduje prázdny riadok, po ktorom nasledujú riadky s detailnejším opisom kódu. Jednoriadkové komentáre sa zvyčajne píšu za značku /// alebo //!. Do spracovávaných komentárov sa môžu pridať príkazy, ktoré napríklad vytvoria odstavce pre dané opisy. Najdôležitejšie sú tieto:

• \author {...} – meno autora
• \brief {...} – stručný opis elementu
• \bug {...} – opis chyby
• \exception - opis výnimky e
• \file - meno súboru
• \param {...} – opis parametru p
• \return {...} – opis návratovej hodnoty
• \see {ref} – odkazy na príbuzné informácie
• \test {...} – zoznam miest, ktoré treba otestovať
• \todo {...} – zoznam toho, čo ešte treba urobiť
• \version {...} – verzia programu
• \warning {...} – varovné správy

Doxygen má niekoľko funkcií, ktoré Javadoc neponúka. Je to generovanie diagramov tried, možnosť linkového pripojenia zdrojového kódu k dokumentácii, podpora prídavných značiek, generovanie výstupu vo viacerých formátoch. Umožňuje tiež mnoho vizuálnych úprav výslednej dokumentácie.

-- MiroslavPorada - 08 May 2011