Utilizzo dei commenti Java

I commenti Java sono note in un file di codice Java che vengono ignorati dal compilatore e dal motore di runtime. Sono utilizzati per annotare il codice al fine di chiarirne il design e lo scopo. È possibile aggiungere un numero illimitato di commenti a un file Java, ma ci sono alcune "best practice" da seguire quando si usano i commenti.

In genere, i commenti sul codice sono commenti di "implementazione" che spiegano il codice sorgente, come descrizioni di classi, interfacce, metodi e campi. Di solito si tratta di un paio di righe scritte sopra o accanto al codice Java per chiarire cosa fa.

Un altro tipo di commento Java è un commento Javadoc. I commenti Javadoc differiscono leggermente nella sintassi dai commenti sull'implementazione e vengono utilizzati dal programma javadoc.exe per generare la documentazione HTML Java.

Perché usare i commenti Java?

È buona norma prendere l'abitudine di inserire commenti Java nel codice sorgente per migliorarne la leggibilità e la chiarezza di sé e degli altri programmatori. Non è sempre immediatamente chiaro cosa sta eseguendo una sezione del codice Java. Alcune righe esplicative possono ridurre drasticamente il tempo necessario per comprendere il codice.

Influiscono sull'esecuzione del programma?

I commenti di implementazione nel codice Java sono lì solo per essere letti dagli umani. I compilatori Java non si preoccupano di loro e durante la compilazione del programma, li ignorano. Le dimensioni e l'efficienza del programma compilato non saranno influenzate dal numero di commenti nel codice sorgente.

Commenti di implementazione

I commenti sull'implementazione sono disponibili in due diversi formati:

Commenti linea: Per un commento di una riga, digita "//" e segui le due barre in avanti con il tuo commento. Per esempio:
```
 // questo è un commento a riga singola
int guessNumber = (int) (Math.random () * 10); 
```
Quando il compilatore incontra le due barre in avanti, sa che tutto ciò che si trova a destra deve essere considerato come un commento. Ciò è utile durante il debug di un pezzo di codice. Aggiungi un commento da una riga di codice di cui stai eseguendo il debug e il compilatore non lo vedrà:
- ```
 // questo è un commento a riga singola
// int guessNumber = (int) (Math.random () * 10); 
```
  Puoi anche usare le due barre per fare un commento di fine riga:
- ```
 // questo è un commento a riga singola
int guessNumber = (int) (Math.random () * 10); // Un commento di fine riga 
```
Commenti blocco: Per iniziare un commento a blocchi, digitare "/ *". Tutto tra la barra e l'asterisco, anche se si trova su una riga diversa, viene trattato come un commento fino a quando i caratteri "* /" terminano il commento. Per esempio:
```
 /* Questo
è
un'
bloccare
commento
* /
/ * così è * /
```

Commenti Javadoc

Usa i commenti speciali di Javadoc per documentare la tua API Java. Javadoc è uno strumento incluso con JDK che genera documentazione HTML dai commenti nel codice sorgente.

Un commento Javadoc in

.Giava

i file di origine sono racchiusi nella sintassi iniziale e finale in questo modo:

/ **

* /

. Ogni commento al loro interno è preceduto da a

Inserisci questi commenti direttamente sopra il metodo, la classe, il costruttore o qualsiasi altro elemento Java che desideri documentare. Per esempio:

// myClass.java
/ **
* Rendi questa una frase sommaria che descrive la tua classe.
* Ecco un'altra riga.
* /
pubblico classe la mia classe

...

Javadoc incorpora vari tag che controllano il modo in cui viene generata la documentazione. Ad esempio, il

@param

tag definisce i parametri di un metodo:

 / ** metodo principale
* @param args String []
* /
pubblico statico vuoto main (String [] args)

System.out.println ("Hello World!");

Molti altri tag sono disponibili in Javadoc e supporta anche tag HTML per aiutare a controllare l'output. Vedi la tua documentazione Java per maggiori dettagli.

Suggerimenti per l'utilizzo dei commenti

Non commentare troppo. Non è necessario spiegare ogni riga del programma. Se il tuo programma scorre in modo logico e non si verifica nulla di inaspettato, non sentire la necessità di aggiungere un commento.
Rientra i tuoi commenti. Se la riga di codice che stai commentando è rientrata, assicurati che il tuo commento corrisponda al rientro.
Mantieni i commenti pertinenti. Alcuni programmatori sono eccellenti nella modifica del codice, ma per qualche motivo dimenticano di aggiornare i commenti. Se un commento non è più applicabile, modificalo o rimuovilo.

Non annidare i commenti di blocco. Quanto segue comporterà un errore del compilatore:

 /* Questo
è
/ * Questo commento di blocco termina il primo commento * /
un'
bloccare
commento
* /

Scienza