5. Commenti
I programmi Java possono avere due tipi di commenti: commenti d’implementazione e commenti di documentazione.
I commenti d’implementazione sono quelli classici del C++, che sono delimitati da /*...*/, e //. I commenti di documentazione (noti anche come “doc comments”) sono esclusivi di Java, e sono delimitati da /**...*/. I doc comments possono essere estratti in file HTML utilizzando lo strumento javadoc.

I commenti d’implementazione sono dei mezzi per commentare il codice o per commentare una particolare implementazione. I doc comments vengono utilizzati per descrivere la specifica del codice, da una prospettiva non implementativa, per essere letti da sviluppatori che non devono necessariamente avere il codice in mano.

I commenti dovrebbero essere usati per dare una panoramica del codice e per fornire informazioni aggiuntive che non sono prontamente disponibili nel codice stesso. I commenti devono contenere solo informazioni rilevanti per leggere e comprendere il programma. Ad esempio, informazioni su come il package corrispondente è costruito o in quale directory risiede non dovrebbero essere incluse in un commento.

Sono appropriate digressioni su decisioni di progetto non futili o non ovvie, ma è consigliabile non duplicare informazioni presenti (in forma chiara) nel codice. E’ molto facile che commenti ridondanti diventino obsoleti; in generale, evitare commenti suscettibili di diventare obsoleti con l’evoluzione del software.

Nota: La frequenza dei commenti talvolta riflette una povera qualità del codice. Quando ci si sente obbligati ad aggiungere un commento, considerare il caso di riscrivere il codice per renderlo più chiaro.

I commenti non dovrebbero essere inclusi in grandi riquadri tracciati con asterischi o altri caratteri, né dovrebbero includere caratteri speciali come backspace.

5.1. Formattazione dei commenti d’implementazione
I programmi possono avere quattro tipi di commenti d’implementazione: di blocco, a linea singola, pendenti e di fine linea.

5.1.1. Commenti di blocco
I commenti di blocco sono usati per fornire descrizioni di file, metodi, strutture dati e algoritmi. I commenti di blocco possono essere usati all’inizio di ogni file e prima di ogni metodo. Possono inoltre essere usati in altri punti, come all’interno dei metodi. I commenti di blocco dentro una funzione o un metodo dovrebbero essere indentati allo stesso livello del codice che descrivono.

Un commento di blocco dovrebbe essere preceduto da una linea bianca per separarlo dal resto del codice.

/*
* Qui c’è un commento di blocco.
*/

I commenti di blocco possono iniziare con /*-, che è riconosciuto da indent(1) come l’inizio di un commento di blocco che non deve essere riformattato. Ad esempio:

/*-
* Qui c’è un commento di blocco con una formattazione
* speciale che voglio che sia ignorata da indent(1).
*
*     uno
*         due
*             tre
*/

Nota: Se non si usa indent(1), non bisogna usare /*- nel codice o fare ogni altra concessione alla possibilità che qualcun altro possa eseguire indent(1) sul codice.

Vedi anche “Commenti di documentazione”.

5.1.2. Commenti a linea singola
Brevi commenti possono apparire su una linea singola indentati al livello del codice che seguono. Se un commento non può essere scritto su una linea singola, deve seguire il formato di commento di blocco (vedi sezione 5.1.1). Un commento a linea singola deve essere preceduto da una linea bianca. Quello che segue è un esempio di commento a linea singola nel codice Java:

if (condizione) {

    /* Gestisce la condizione. */
    ...
}

5.1.3. Commenti pendenti
Brevissimi commenti possono apparire sulla stessa linea del codice che descrivono, ma devono essere spostati sufficientemente da separarli dalle istruzioni. Se più commenti brevi appaiono in un frammento di codice, questi devono essere indentati con la stessa tabulazione. Ecco un esempio di commento pendente nel codice Java:

if (a == 2) {
    return TRUE;             /* caso speciale */
} else {
    return numeroPrimo(a);         /* eseguito solo per a dispari */
}

5.1.4. Commenti di fine linea
Il delimitatore di commento // può commentare una linea completa o una parte della linea. Non dovrebbe essere usato su più linee consecutive per commenti testuali; comunque, può essere usato su più linee consecutive per commentare sezioni del codice. Seguono tre esempi dei tre stili:

if (foo > 1) {

    // Fa qualcosa.
    ...
}
else{
    return false; // Spiega perché qui.
}

//if (bar > 1) {
//
//    // Fa qualcos’altro.
//    ...
//}
//else{
//    return false;
//}

Torna all'indice Generale del corso di Specifiche Sun di Software Planet