Kā izmantot komentārus Java kodā

Java komentāri ir piezīmes Java koda failā, kuras kompilators un izpildlaika dzinējs ignorē. Tos izmanto koda anotēšanai, lai precizētu tā dizainu un mērķi. Java failam var pievienot neierobežotu skaitu komentāru, taču, izmantojot komentārus, ir jāievēro dažas “labākās prakses”.

Parasti koda komentāri ir "ieviešanas" komentāri, kas izskaidro avota kods, piemēram, klašu, saskarņu, metožu un lauku apraksti. Parasti tās ir pāris rindiņas, kas rakstītas virs vai blakus Java kodam, lai precizētu, ko tas dara.

Cits Java komentāru veids ir Javadoc komentārs. Javadoc komentāru sintakse nedaudz atšķiras no ieviešanas komentāriem, un programma javadoc.exe tos izmanto Java HTML dokumentācijas ģenerēšanai.

Labā prakse ir pierast pie ieraduma ievietot Java komentārus savā avota kodā, lai uzlabotu tā lasāmību un skaidrību sev un citiem programmētājiem. Ne vienmēr uzreiz ir skaidrs, kādu Java koda sadaļu veic. Dažas skaidrojošās rindiņas var krasi samazināt laiku, kas nepieciešams koda izpratnei.

Komentāri par ieviešanu Java kods ir tikai cilvēkiem lasīt. Java kompilatori viņiem nerūp un kad programmas sastādīšana, viņi vienkārši izlaiž viņus pāri. Jūsu apkopotās programmas lielumu un efektivitāti neietekmēs jūsu avota kodā esošo komentāru skaits.

Komentāri par ieviešanu ir divos dažādos formātos:

• Rindas komentāri: Komentāriem vienā rindā ierakstiet "//" un izpildiet divus komentārus uz priekšu. Piemēram:

   // tas ir vienas rindas komentārs
  int guessNumber = (int) (Math.random () * 10); 

  Kad kompilators sastopas ar divām slīpsvītēm uz priekšu, viņš zina, ka viss, kas no tām atrodas labajā pusē, ir jāuzskata par komentāru. Tas ir noderīgi, atkļūdot koda gabalu. Vienkārši pievienojiet komentāru no tā koda līnijas, kuru jūs atkļūdojat, un kompilators to neredzēs:

  •  // tas ir vienas rindas komentārs
    // int guessNumber = (int) (Math.random () * 10); 

    Varat arī izmantot divas slīpsvītnes uz priekšu, lai komentētu rindas beigas:

  •  // tas ir vienas rindas komentārs
    int guessNumber = (int) (Math.random () * 10); // Rindas beigu komentārs 

• Bloķēt komentārus: Lai sāktu bloķēt komentāru, ierakstiet "/ *". Viss, kas atrodas starp priekšējo slīpsvītru un zvaigznīti, pat ja tas atrodas citā rindiņā, tiek uzskatīts par komentāru, līdz rakstzīmes "* /" beidz komentāru. Piemēram:

   / * šo 
  ir 
  a
  bloķēt
  komentēt
  */
  / * tā tas ir * /
  

Izmantojiet īpašus Javadoc komentārus, lai dokumentētu savu Java API. Javadoc ir JDK iekļauts rīks, kas ģenerē HTML dokumentāciju no avota koda komentāriem.

Javadoc komentārs iekšā

.java

/**

*/

*

Novietojiet šos komentārus tieši virs metodes, klases, konstruktora vai jebkura cita Java elementa, kuru vēlaties dokumentēt. Piemēram:

// myClass.java
/**
* Izveidojiet šo kopsavilkuma teikumu, kurā aprakstīta jūsu klase.
* Šeit ir vēl viena līnija.
*/
publiskiklase mana klase
{
...
}

Javadoc iekļauj dažādus tagus, kas kontrolē dokumentācijas ģenerēšanu. Piemēram,

@param

 / ** galvenā metode
* @param args stīga []
*/​
publiskistatiskstukšums galvenais (stīgu [] args)
​{
System.out.println ("Sveika pasaule!");
}

Javadoc ir pieejami daudzi citi tagi, un tas arī atbalsta HTML tagus, lai palīdzētu kontrolēt izvadi. Sīkāku informāciju skatiet Java dokumentācijā.

• Nekomentējiet. Katra jūsu programmas līnija nav jāpaskaidro. Ja jūsu programma plūst loģiski un nenotiek nekas negaidīts, nejūtiet vajadzību pievienot komentāru.
• Atgādiniet savus komentārus. Ja koda rindiņa, kuru komentējat, ir atkāpe, pārliecinieties, vai komentārs atbilst atkāpei.
• Saglabājiet komentārus atbilstošos. Daži programmētāji lieliski izmaina kodu, taču kaut kādu iemeslu dēļ aizmirst atjaunināt komentārus. Ja komentāru vairs nepiemēro, mainiet vai noņemiet to.
• Nelieciet ligzdā bloķēt komentārus. Šāds rezultāts radīs kompilatora kļūdu:

   / * šo 
  ir
  / * Šis bloķētais komentārs pabeidz pirmo komentāru * /
  a
  bloķēt
  komentēt
  */