I commenti in Java

Scrivere commenti nel codice Java è un'arte che può fare una grande differenza nella comprensibilità del codice, non solo per te, ma anche per chiunque altro lo legga in futuro.

A cosa servono i commenti in un programma? I commenti sono delle parti non eseguibili dal compilatore. Quindi non hanno una funzione algoritmica. Servono a spiegare agli altri programmatori cosa fa il codice, perché è stato scritto in un certo modo e quali sono i concetti chiave da comprendere. In questo modo è più facile da modificare in futuro.

Nel linguaggio Java esistono diversi modi per inserire un commento nel codice.

Commenti a linea singola (`//`)

Questi commenti sono utilizzati per spiegare singole linee di codice o piccoli blocchi.

Sono molto utili per dare un rapido contesto.

// Controlla se l'utente ha l'età minima per accedere
if (eta >= 18) {
    System.out.println("Accesso consentito");
}

In questo esempio, il commento spiega chiaramente lo scopo della condizione. Anche se il codice è semplice, il commento lo rende immediatamente comprensibile.

Commenti a blocco (`/* ... */`)

I commenti a blocco del tipo /* ... */ sono ideali per spiegare sezioni più grandi di codice o per dare un'introduzione a una funzione o a una classe.

/*
 * Questa funzione calcola il fattoriale di un numero.
 * Il fattoriale di n è il prodotto di tutti i numeri interi positivi minori o uguali a n.
 * Esempio: 5! = 5 * 4 * 3 * 2 * 1 = 120
 */
public int fattoriale(int n) {
    if (n == 0) {
        return 1; // Il fattoriale di 0 è 1 per definizione
    } else {
        return n * fattoriale(n - 1); // Ricorsione per calcolare il fattoriale
    }
}

In questo caso, il commento spiega sia cosa fa la funzione, sia un esempio concreto di come funziona.

Questo è molto utile soprattutto per chi potrebbe non essere familiare con il concetto di fattoriale.

Per convenzione ogni riga del blocco di codice deve cominciare con un asterisco "*" che permette al lettore di avere una migliore visione dell'estensione del commento.

Commenti Javadoc (`/** ... */`)

I commenti del tipo /** ... /* sono speciali perché vengono utilizzati per generare la documentazione automatica del codice.

Sono posti sopra classi, metodi o variabili e descrivono la funzionalità in modo formale.

/**
 * Questa classe rappresenta un cerchio con un certo raggio.
 * Offre metodi per calcolare l'area e la circonferenza.
 */
public class Cerchio {
    private double raggio;

    /**
     * Costruttore della classe Cerchio.
     * @param raggio Il raggio del cerchio.
     */
    public Cerchio(double raggio) {
        this.raggio = raggio;
    }

    /**
     * Calcola l'area del cerchio.
     * @return L'area del cerchio.
     */
    public double calcolaArea() {
        return Math.PI * Math.pow(raggio, 2);
    }

    /**
     * Calcola la circonferenza del cerchio.
     * @return La circonferenza del cerchio.
     */
    public double calcolaCirconferenza() {
        return 2 * Math.PI * raggio;
    }
}

Qui, i commenti Javadoc spiegano cosa fa la classe e i suoi metodi.

Usando la sintassi Javadoc, puoi anche includere tag speciali come `@param` per descrivere i parametri e `@return` per descrivere il valore restituito.

Anche in questo caso, per convenzione ogni riga del commento JavaDoc ( Java Documentation Comment ) deve cominciare con un asterisco "*".

Consigli pratici per inserire i commenti

Per finire ecco qualche consiglio pratico per scrivere dei commenti efficaci.

• Sii chiaro e conciso: I commenti dovrebbero essere brevi e dritti al punto. Evita di scrivere romanzi!
• Evita di spiegare l'ovvio: Non è necessario commentare ogni singola linea di codice, soprattutto se il codice è autoesplicativo. Ad esempio, non c'è bisogno di commentare una riga come `int a = 5; // Imposta a a 5`, a meno che non ci sia un motivo particolare per farlo.
• Aggiorna i commenti: Se cambi il codice, assicurati di aggiornare anche i commenti. Niente è peggio di un commento che non corrisponde più al codice!
• Usa commenti per spiegare il "perché": Il codice mostra "cosa" fa il programma, ma i commenti dovrebbero spiegare "perché" fa una certa cosa, specialmente se c'è una logica non immediata.

Ricorda che scrivere buoni commenti è una parte essenziale per diventare un buon programmatore.

Non solo migliora la tua capacità di capire il tuo codice in futuro, ma rende anche il lavoro più facile per chiunque altro debba lavorare sullo stesso progetto.