Ako používať komentáre v kóde Java

Komentáre Java sú poznámky v súboroch kódu Java, ktoré ignoruje kompilátor a modul runtime. Používajú sa na anotáciu kódu s cieľom objasniť jeho návrh a účel. Do súboru Java môžete pridať neobmedzený počet komentárov, ale pri používaní komentárov je potrebné postupovať podľa niektorých „osvedčených postupov“.

Všeobecne sú komentáre k kódu „implementačné“ pripomienky, ktoré vysvetľujú zdrojový kód, napríklad popisy tried, rozhraní, metód a polí. Zvyčajne ide o niekoľko riadkov napísaných nad alebo vedľa Java kódu, aby sa objasnilo, čo robí.

Ďalším typom komentára Java je komentár Javadoc. Komentáre Javadoc sa mierne líšia v syntaxi od implementačných komentárov a používa ich program javadoc.exe na vygenerovanie Java HTML dokumentácie.

Je dobré zvyknúť si do zdrojového kódu vkladať komentáre Java, aby ste zvýšili jeho čitateľnosť a prehľadnosť pre seba a ostatných programátorov. Nie je vždy jasné, čo robí časť kódu Java. Niekoľko vysvetľujúcich riadkov môže drasticky skrátiť čas potrebný na pochopenie kódu.

Pripomienky k implementácii v roku 2007 Java kód sú tu len ľudia, ktorí si ich môžu prečítať. Kompilátory Java sa o nich nestarajú a kedy zostavenie programu, proste ich preskočia. Počet komentárov v zdrojovom kóde nebude ovplyvnený veľkosť a efektívnosť kompilovaného programu.

Pripomienky k implementácii prichádzajú v dvoch rôznych formátoch:

• Komentáre k riadkom: Pre jednoriadkový komentár napíšte „//“ a nasledujte dve lomky s komentárom. Napríklad:

   // Toto je jednoriadkový komentár
  int guessNumber = (int) (Math.random () * 10); 

  Keď kompilátor narazí na dve predné lomky, vie, že všetko, čo je napravo od nich, treba považovať za komentár. Je to užitočné pri ladení časti kódu. Stačí pridať komentár z riadku kódu, ktorý ladíte, a kompilátor ho neuvidí:

  •  // Toto je jednoriadkový komentár
    // int guessNumber = (int) (Math.random () * 10); 

    Na koniec riadku môžete použiť aj dve lomky:

  •  // Toto je jednoriadkový komentár
    int guessNumber = (int) (Math.random () * 10); // Komentár konca riadku 

• Blokovať komentáre: Ak chcete začať blokovať komentár, zadajte „/ *“. Všetko medzi lomkou a hviezdičkou, aj keď je na inom riadku, sa považuje za komentár, až kým znaky „* /“ neukončia komentár. Napríklad:

   / * toto 
  je 
  
  blok
  komentár
  */
  / * tak to je * /
  

Na zdokumentovanie rozhrania Java API použite špeciálne komentáre Javadoc. Javadoc je nástroj zahrnutý v JDK, ktorý generuje HTML dokumentáciu z komentárov v zdrojovom kóde.

Javadoc komentár v

.java

/**

*/

*

Umiestnite tieto komentáre priamo nad metódu, triedu, konštruktora alebo iný prvok Java, ktorý chcete dokumentovať. Napríklad:

// myClass.java
/**
* Urobte toto súhrnnú vetu popisujúcu vašu triedu.
* Tu je ďalší riadok.
*/
verejnosťtrieda moja trieda
{
...
}

Javadoc obsahuje rôzne značky, ktoré určujú, ako sa bude dokumentácia generovať. Napríklad

@param

 / ** hlavná metóda
* @param args String []
*/​
verejnosťstatickýprázdno main (String [] args)
​{
System.out.println („Ahoj svet!“);
}

Mnoho ďalších značiek je k dispozícii v Javadoc a tiež podporuje HTML značky, ktoré pomáhajú riadiť výstup. Ďalšie podrobnosti nájdete v dokumentácii k jazyku Java.

• Nepridávajte komentár. Každý riadok vášho programu nemusí byť vysvetlený. Ak váš program prebieha logicky a nedochádza k neočakávaným udalostiam, necítite potrebu pridať komentár.
• Odsadiť svoje komentáre. Ak je riadok kódu, ktorý komentujete, odsadený, uistite sa, že sa váš komentár zhoduje s odsadením.
• Udržujte poznámky relevantné. Niektorí programátori vynikajú v úprave kódu, ale z nejakého dôvodu zabudnite aktualizovať komentáre. Ak komentár už neplatí, upravte ho alebo odstráňte.
• Nevkladajte komentáre blokovania. Výsledkom bude chyba kompilátora:

   / * toto 
  je
  / * Tento komentár blokuje prvý komentár * /
  
  blok
  komentár
  */