Commenti in Java

I commenti sono testo che il compilatore ignora. Esistono per le persone che leggono il codice sorgente. Java ha tre tipi — riga singola, multi-riga e Javadoc — ciascuno con il proprio ruolo.

Questo capitolo tratta la sintassi per tutti e tre gli stili, come generare documentazione HTML da Javadoc e — altrettanto importante — quando un commento vale la pena di essere scritto e quando aggiunge solo rumore. Se sei nuovo alla struttura di Java, leggi prima Java Syntax.

Commenti su riga singola — //

Tutto ciò che segue // fino alla fine della riga è un commento:

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

Usali per brevi note accanto a una riga di codice, o per disabilitare temporaneamente una riga durante il debug.

Commenti multi-riga — /* ... */

Tutto ciò che si trova tra /* e */ viene ignorato, anche su più righe:

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

I commenti multi-riga possono comparire anche inline:

int width = 800 /* pixels */;

Non è possibile annidarli: /* outer /* inner */ */ termina al primo */, lasciando caratteri */ spuri che non vengono compilati. Per "commentare" un blocco che contiene già /* … */, usa // su ogni riga (il tuo IDE ha una scorciatoia — di solito Ctrl+/ / Cmd+/).

Commenti Javadoc — /** ... */

I commenti Javadoc iniziano con /** (nota: due asterischi) e vengono letti dallo strumento javadoc per generare documentazione HTML:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

I commenti Javadoc vengono inseriti immediatamente sopra la classe, il metodo o il campo che descrivono. La prima frase diventa la riga di riepilogo nella documentazione generata.

I tag più utili:

• @param name description — uno per parametro
• @return description — ciò che il metodo restituisce
• @throws ExceptionClass description — quando il metodo lancia un'eccezione
• @see ClassOrLink — riferimento incrociato
• @since 1.5 — da quando questa API è stata aggiunta
• @deprecated reason — sconsiglia ulteriori utilizzi (il compilatore avverte anche lui)

L'intera libreria standard è documentata con Javadoc; gli IDE la leggono per alimentare i loro tooltip.

Generare la documentazione HTML

Lo strumento javadoc viene fornito con il JDK. Puntalo ai tuoi file sorgente (o pacchetti) e scriverà un sito HTML navigabile:

javadoc -d docs Greeter.java

Il flag -d docs sceglie la directory di output. Apri docs/index.html in un browser per vedere le pagine generate — lo stesso layout che trovi nella documentazione ufficiale delle API di Oracle, costruito dai commenti sopra ogni classe e metodo.

Quando commentare, quando no

Un buon codice è la propria documentazione. I commenti che riformulano ciò che il codice già mostra aggiungono solo rumore e diventano rapidamente obsoleti:

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

I commenti guadagnano il loro posto quando spiegano il perché, non il cosa:

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

O quando documentano un vincolo non ovvio:

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

Per le API pubbliche, scrivi Javadoc. Per il codice interno, scrivi solo i commenti che aiutano il prossimo lettore a prendere una decisione.

Una dimostrazione

Il compilatore rimuove tutti e tre gli stili di commento prima di generare il bytecode, quindi hanno un costo zero a runtime.

Cosa fare dopo

Ora che sai come documentare il codice, passa ai mattoni che descrive:

• Java Variables — dichiarazione, inizializzazione e scope.
• Java Syntax — istruzioni, blocchi e le regole che il compilatore impone.
• Java Hello World — il programma minimale in cui vivono i tuoi commenti.

Esercitazione