Kuidas kasutada Java-koodis kommentaare

Java kommentaarid on Java-koodifaili märkused, mida kompilaator ja käitusmootor ignoreerivad. Neid kasutatakse koodi märkimiseks, et selgitada selle ülesehitust ja otstarvet. Võite Java-failile lisada piiramatu arvu kommentaare, kuid kommentaaride kasutamisel tuleb järgida mõnda parimat tava.

Üldiselt on koodikommentaarid "rakendamise" kommentaarid, mis selgitavad lähtekood, näiteks klasside, liideste, meetodite ja väljade kirjeldused. Need on tavaliselt paar rida, mis on kirjutatud Java-koodi kohale või kõrvale, et selgitada, mida see teeb.

Teine Java-kommentaari tüüp on Javadoci kommentaar. Javadoci kommentaarid erinevad süntaksis rakenduskommentaaridest pisut ja neid kasutab programm javadoc.exe Java HTML-dokumentide genereerimiseks.

Hea tava on hakata kombeks panna Java kommentaare oma lähtekoodi, et parandada selle loetavust ja selgust nii endale kui teistele programmeerijatele. Alati pole kohe selge, mida Java-koodi osa täidab. Mõned selgitavad read võivad koodi mõistmiseks kuluvat aega drastiliselt vähendada.

Kommentaarid rakendamise kohta Java kood on olemas ainult inimestele lugemiseks. Java kompilaatorid ei hooli neist ja millal programmi koostamine, jäävad nad lihtsalt nende vahele. Lähtekoodis olevate kommentaaride arv ei mõjuta teie kompileeritud programmi suurust ja tõhusust.

Rakenduse kommentaarid on kahes erinevas vormingus:

• Rea kommentaarid: Üherealise kommentaari jaoks tippige "//" ja järgige oma kommentaariga kahte edasi-tagasi kaldumist. Näiteks:

   // see on üherealine kommentaar
  int guessNumber = (int) (matemaatika.omand () * 10); 

  Kui kompilaator puutub kokku kahe ettepoole kaldkriipsuga, teab ta, et kõike neist paremal tuleb pidada kommentaariks. See on kasulik kooditüki silumisel. Lisage lihtsalt kommentaar silumisele koodirealt ja kompilaator ei näe seda:

  •  // see on üherealine kommentaar
    // int aimNumber = (int) (matemaatika.omand () * 10); 

    Reaalase kommentaari tegemiseks võite kasutada ka kahte ettepoole kaldkriipsu:

  •  // see on üherealine kommentaar
    int guessNumber = (int) (matemaatika.omand () * 10); // rea lõpu kommentaar 

• Blokeeri kommentaarid: Blokeeritava kommentaari alustamiseks tippige "/ *". Kõiki kaldkriipsu ja tärnide vahel, isegi kui need asuvad teisel real, käsitletakse kommentaarina, kuni märgid "/ /" lõpevad kommentaariga. Näiteks:

   / * see 
  on 
  a
  blokeerida
  kommentaar
  */
  / * nii see on * /
  

Java API dokumenteerimiseks kasutage spetsiaalseid Javadoci kommentaare. Javadoc on JDK-ga kaasas olev tööriist, mis genereerib HTML-dokumendid lähtekoodi kommentaaridest.

Javadoci kommentaar

.java

/**

*/

*

Pange need kommentaarid otse meetodi, klassi, konstruktori või mõne muu Java-elemendi kohale, mida soovite dokumenteerida. Näiteks:

// myClass.java
/**
* Tehke sellest oma klassi kirjeldav kokkuvõtlik lause.
* Siin on veel üks rida.
*/
avalikklass minu klass
{
...
}

Javadoc sisaldab erinevaid silte, mis kontrollivad dokumentide genereerimist. Näiteks

@param

 / ** põhimeetod
* @param args String []
*/​
avalikstaatilinetühine peamine (keelpill [] args)
​{
System.out.println ("Tere maailm!");
}

Javadocis on saadaval palju muid silte ja see toetab ka HTML-silte, mis aitavad väljundit juhtida. Lisateavet leiate oma Java dokumentatsioonist.

• Ärge kommenteerige üle. Teie programmi iga rida ei pea selgitama. Kui teie programm voolab loogiliselt ja midagi ootamatut ei toimu, ärge tundke vajadust kommentaari lisada.
• Taande lisamine oma kommentaaridele. Kui kommenteeritav koodirida on taane, veenduge, et teie kommentaar vastaks taandele.
• Hoidke kommentaarid asjakohased. Mõned programmeerijad oskavad koodi muuta suurepäraselt, kuid unustavad mingil põhjusel kommentaare värskendada. Kui kommentaari enam ei kohaldata, muutke seda või eemaldage see.
• Ärge peske blokeerige kommentaare. Järgnev põhjustab kompilaatori tõrke:

   / * see 
  on
  / * Selle ploki kommentaar lõpetab esimese kommentaari * /
  a
  blokeerida
  kommentaar
  */