Slik bruker du kommentarer i Java-kode

Java-kommentarer er notater i en Java-kodefil som blir ignorert av kompilatoren og runtime-motoren. De brukes til å kommentere koden for å tydeliggjøre utformingen og formålet. Du kan legge til et ubegrenset antall kommentarer til en Java-fil, men det er noen "beste fremgangsmåter" å følge når du bruker kommentarer.

Generelt er kodekommentarer "implementering" -kommentarer som forklarer kildekode, for eksempel beskrivelser av klasser, grensesnitt, metoder og felt. Dette er vanligvis et par linjer skrevet over eller ved siden av Java-kode for å tydeliggjøre hva den gjør.

En annen type Java-kommentar er en Javadoc-kommentar. Javadoc-kommentarer skiller seg litt i syntaks fra implementeringskommentarer og brukes av programmet javadoc.exe til å generere Java HTML-dokumentasjon.

Det er god praksis å sette seg inn i vanen med å sette Java-kommentarer i kildekoden for å forbedre lesbarheten og klarheten for deg selv og andre programmerere. Det er ikke alltid umiddelbart klart hva en del av Java-koden utfører. Noen få forklarende linjer kan redusere tiden det tar å forstå koden drastisk.

Implementeringskommentarer i Java-kode er bare der for mennesker å lese. Java-kompilatorer bryr seg ikke om dem og når kompilere programmet, hopper de bare over dem. Størrelsen og effektiviteten til det kompilerte programmet ditt påvirkes ikke av antall kommentarer i kildekoden.

Implementeringskommentarer kommer i to forskjellige formater:

• Linjekommentarer: For en kommentar på en linje, skriv "//" og følg de to skråstrekene fremover med kommentaren din. For eksempel:

   // dette er en enkeltlinjekommentar
  int guessNumber = (int) (Math.random () * 10); 

  Når kompilatoren kommer over de to skråstrekene, vet den at alt til høyre for dem er å anse som en kommentar. Dette er nyttig når du feilsøker et stykke kode. Bare legg til en kommentar fra en kodelinje du feilsøker, og kompilatoren vil ikke se den:

  •  // dette er en enkeltlinjekommentar
    // int guessNumber = (int) (Math.random () * 10); 

    Du kan også bruke de to skråstrekene for å gjøre en slutt på kommentaren:

  •  // dette er en enkeltlinjekommentar
    int guessNumber = (int) (Math.random () * 10); // En sluttkommentar 

• Blokker kommentarer: For å starte en blokkkommentar, skriv "/ *". Alt mellom skråstreken og stjerne, selv om det er på en annen linje, blir behandlet som en kommentar til karakterene "* /" avslutter kommentaren. For eksempel:

   / * dette 
  er 
  en
  blokkere
  kommentar
  */
  / * så er dette * /
  

Bruk spesielle Javadoc-kommentarer for å dokumentere Java API-en. Javadoc er et verktøy som følger med JDK som genererer HTML-dokumentasjon fra kommentarer i kildekoden.

En Javadoc-kommentar i

.java

/**

*/

*

Plasser disse kommentarene rett over metoden, klassen, konstruktøren eller andre Java-elementer du vil dokumentere. For eksempel:

// myClass.java
/**
* Lag dette til en oppsummerende setning som beskriver klassen din.
* Her er en annen linje.
*/
offentligklasse klassen min
{
...
}

Javadoc har forskjellige tagger som styrer hvordan dokumentasjonen genereres. For eksempel

@param

 / ** hovedmetode
* @param args String []
*/​
offentligstatisktomrom main (String [] args)
​{
System.out.println ("Hello World!");
}

Mange andre tagger er tilgjengelige i Javadoc, og den støtter også HTML-koder for å kontrollere utdataene. Se Java-dokumentasjonen for mer detalj.

• Ikke overkommentar. Hver linje i programmet ditt trenger ikke å bli forklart. Hvis programmet flyter logisk og ingenting uventet oppstår, må du ikke føle behov for å legge til en kommentar.
• Innrykk dine kommentarer. Hvis kodelinjen du kommenterer er innrykket, må du forsikre deg om at kommentaren din samsvarer med innrykket.
• Hold kommentarer relevante. Noen programmerere er gode på å endre kode, men glem av en eller annen grunn å oppdatere kommentarene. Hvis en kommentar ikke lenger gjelder, må du enten endre eller fjerne den.
• Ikke hekk blokker kommentarer. Følgende vil resultere i en kompilatorfeil:

   / * dette 
  er
  / * Denne blokkeringskommentaren fullfører den første kommentaren * /
  en
  blokkere
  kommentar
  */