Commenti in Java: su una riga, su più righe e Javadoc

A cosa servono i commenti

Un commento è testo nel codice sorgente che il compilatore Java ignora completamente. Non diventa mai parte del programma in esecuzione: esiste solo per le persone che leggono il codice. Usi i commenti per spiegare perché qualcosa è fatto in un certo modo, per lasciare promemoria o per disattivare temporaneamente del codice senza cancellarlo.

Java ha tre tipi di commenti: su una riga (//), a blocco su più righe (/* */) e di documentazione Javadoc (/** */). Fanno tutti lo stesso lavoro di base, cioè essere ignorati in fase di compilazione, ma ognuno si usa in situazioni diverse.

Commenti su una riga

Due barre (//) aprono un commento che arriva fino alla fine della riga corrente. Il compilatore salta tutto ciò che va dal // all'a capo.

public class Main {
    public static void main(String[] args) {
        // Stampa un saluto nella console
        System.out.println("Hello, Java!");

        int score = 90; // un commento può anche stare dopo il codice
        System.out.println(score);
    }
}

Nota che il secondo commento condivide la riga con del codice vero. Tutto ciò che sta prima di // viene comunque eseguito; solo la parte successiva viene ignorata. È lo stile di commento più comune per le note brevi.

Commenti a blocco su più righe

Quando la tua nota occupa più righe, un commento a blocco è più pulito che anteporre // a ogni riga. Un commento a blocco inizia con /* e termina con */. Tutto ciò che sta in mezzo, su quante righe vuoi, viene ignorato.

public class Main {
    public static void main(String[] args) {
        /*
         * Questo programma mostra un commento a blocco.
         * Gli asterischi all'inizio di ogni riga sono solo una
         * convenzione per la leggibilità: non sono obbligatori.
         */
        System.out.println("Block comments are handy.");
    }
}

I caratteri * allineati lungo il bordo sono una convenzione di stile, non una regola. Le uniche parti che contano davvero sono l'apertura /* e la chiusura */.

Commentare il codice

I commenti sono il modo standard per disattivare del codice mentre fai esperimenti, senza cancellarlo. Usa // per una singola riga, oppure un commento a blocco per spegnere più righe in una volta.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Eseguilo e vedrai stampate solo le due righe con "runs". Le chiamate println commentate sono invisibili al compilatore.

Una trappola comune: i commenti a blocco non si annidano. Il primo */ chiude il commento, indipendentemente da quanti /* lo precedono. Quindi non puoi racchiudere un blocco /* ... */ dentro un altro blocco /* ... */: il */ interno chiude tutto e il resto diventa un errore di sintassi. Se devi disattivare una zona che contiene già commenti a blocco, usa // su ogni riga (la maggior parte degli editor lo fa con una sola scorciatoia da tastiera).

Commenti di documentazione Javadoc

Un commento Javadoc sembra un commento a blocco ma inizia con /**, cioè con due asterischi. Serve a documentare una classe, un metodo o un campo, e si trova subito sopra l'elemento che descrive. Lo strumento javadoc li trasforma in documentazione API in HTML consultabile, e gli IDE li mostrano come suggerimenti al passaggio del mouse.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

I tag @param, @return e @throws sono campi strutturati che gli strumenti capiscono. Per il compilatore resta solo un commento ignorato: il valore sta tutto nella documentazione che produce e nei suggerimenti dell'IDE che dà agli altri sviluppatori (e a te, fra sei mesi).

Commenti utili e rumore

Un commento dovrebbe spiegare qualcosa che il codice non può dire da solo. I commenti che si limitano a ripetere il codice aggiungono confusione e tendono a diventare obsoleti quando il codice cambia.

// Male: ripete soltanto ciò che il codice fa in modo evidente
int i = i + 1; // aggiunge uno a i

// Meglio: spiega il motivo, che il codice non può mostrare
retries++; // attendi e riprova; l'API è limitata a 5 richieste/sec

Cerca di rendere leggibile il codice con nomi e struttura chiari, e riserva i commenti al perché: intenzioni, compromessi, casi limite e collegamenti al contesto. Se ti ritrovi a scrivere un commento per spiegare una riga poco chiara, spesso è il segnale che conviene rinominare una variabile o estrarre un metodo.

Prossimo passo: le variabili

Ora che sai annotare il tuo codice, il prossimo mattone è memorizzarci dei dati. La prossima pagina parla delle variabili: come dichiararle, i tipi che contengono e le regole che Java impone perché è a tipizzazione statica.