Commenti in C++: su una riga // e su più righe /* */

A cosa servono i commenti

Un commento è testo nel tuo codice sorgente che il compilatore C++ ignora completamente. Non arriva mai nel programma compilato: esiste solo per le persone che leggono il codice. Usi i commenti per spiegare perché una cosa è fatta in un certo modo, per lasciare promemoria o per disattivare temporaneamente del codice senza cancellarlo.

Partendo dalla sintassi del C++ che già conosci, i commenti sono una delle poche cose che puoi mettere quasi ovunque e che il compilatore semplicemente salterà. Il C++ ne ha due tipi: su una riga (//) e a blocco su più righe (/* */).

Commenti su una riga

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

#include <iostream>
using namespace std;

int main() {
    // Stampa un saluto nella console
    cout << "Hello, C++!" << endl;

    int score = 90; // un commento può anche stare dopo il codice
    cout << score << endl;
    return 0;
}

Nota che il secondo commento condivide la riga con del codice vero. Tutto ciò che sta prima del // 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 diverse righe, un commento a blocco è più pulito che mettere // davanti a ogni riga. Un commento a blocco inizia con /* e termina con */. Tutto ciò che sta tra i due, per quante righe siano, viene ignorato.

#include <iostream>
using namespace std;

int main() {
    /*
     * Questo programma mostra un commento a blocco.
     * Gli asterischi all'inizio di ogni riga sono solo una
     * convenzione per la leggibilità: non sono obbligatori.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

I caratteri * allineati lungo il margine sono una convenzione di stile, non una regola. Le uniche parti che contano davvero sono il /* di apertura e il */ di chiusura. Un commento a blocco può perfino stare a metà riga (int x = 5 /* width */ + 2; è valido), anche se così diventa presto difficile da leggere.

Commentare il codice

I commenti sono il modo standard per disattivare del codice mentre sperimenti, senza cancellarlo. Usa // per una singola riga, o un commento a blocco per spegnere più righe insieme.

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

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

Il problema dell'annidamento

Una trappola in cui cadono i principianti: i commenti a blocco non si annidano. Il primo */ chiude il commento, indipendentemente da quanti /* ci siano stati prima. Quindi non puoi racchiudere un blocco /* ... */ dentro un altro blocco /* ... */: il */ interno chiude tutto, e ciò che segue torna a essere codice (di solito con un errore di sintassi).

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

Il commento esterno termina al */ dopo the width, quindi il resto non è più commentato e il compilatore si blocca sul */ finale. Quando devi disattivare una regione che contiene già commenti a blocco, usa invece // su ogni riga. La maggior parte degli editor attiva o disattiva i commenti di riga su un'intera selezione con una sola scorciatoia da tastiera, il che evita del tutto il problema.

Commenti utili e rumore

Un commento dovrebbe spiegare qualcosa che il codice non riesce a dire da solo. I commenti che si limitano a ripetere il codice aggiungono disordine e tendono a diventare obsoleti man mano che il codice cambia.

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Cerca di rendere leggibile il codice con nomi chiari e una buona struttura, 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 confusa, spesso è un segnale che dovresti rinominare una variabile o dividere la logica in una funzione con un nome chiaro.

Prossimo: Variabili

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