Commenti in C: // e /* */ spiegati

Un commento è testo che il compilatore butta via. Esiste solo per le persone che leggeranno il codice in seguito, e una di queste di solito sei tu. Il C offre due forme, e capire quando usare l'una o l'altra richiede circa due minuti.

Le due forme

#include <stdio.h>

int main(void) {
    // Un commento su una riga: tutto ciò che segue // fino a fine riga.

    /* Un commento a blocco.
       Può occupare tutte le righe che vuoi
       e termina solo al marcatore di chiusura. */

    printf("I commenti non arrivano mai nell'output.\n");  // possono anche seguire il codice
    return 0;
}

Eseguilo: l'output è una sola riga. Entrambi i commenti sono stati eliminati prima ancora che il compilatore analizzasse il programma: non costano nulla a runtime e non aggiungono nulla all'eseguibile.

// arriva fino alla fine della riga fisica. Su quella riga non può seguire nient'altro, quindi questo non funziona come sembra:

int x = 5;  // imposta x a cinque  int y = 6;   /* y non viene mai dichiarata */

/* ... */ termina al primo */, ovunque si trovi. Può iniziare e finire a metà riga, cosa che ogni tanto è utile:

int total = price /* tasse escluse */ + shipping;

Perché esistono due stili

/* */ è il C originale, del 1972. // arriva dal C++ ed è stato aggiunto ufficialmente al C solo con C99. Questa storia spiega una cosa che noterai leggendo codice più vecchio: le librerie scritte per essere portabili su C89 usano /* */ anche per i commenti di una riga, perché // non compilerebbe sulle vecchie toolchain che supportavano ancora.

Oggi ogni compilatore che probabilmente userai accetta entrambi. Usa // per le note normali e /* */ quando un commento occupa davvero più righe. Se lavori con un compilatore embedded molto vecchio, verifica prima di affidarti a //.

I commenti non si annidano

Questa è l'unica vera trappola:

/* Disattiva questa sezione per ora
   int a = compute();
   /* il classico helper: tienilo d'occhio */
   int b = a * 2;
*/

Il commento a blocco termina al primo */, quello sulla riga 3. Le righe 4 e 5 tornano quindi a essere codice attivo, e il */ finale sulla riga 6 è un errore di sintassi. Il messaggio del compilatore indica l'ultima riga e non aiuta per niente a capire la causa.

La soluzione è usare invece il preprocessore, che gestisce l'annidamento:

#if 0
    int a = compute();
    /* il classico helper: tienilo d'occhio */
    int b = a * 2;
#endif

#if 0 non è mai vero, quindi il preprocessore elimina tutto fino a #endif prima che il compilatore lo veda. Funziona anche con commenti, virgolette e altri blocchi #if all'interno, ed è facile da cercare quando fai pulizia.

Commentare codice durante il debug

Rimuovere temporaneamente una riga è l'uso quotidiano più comune dei commenti. Quando un programma si comporta male, disattivare un'istruzione alla volta ti dice quale conta.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("passo %d: total = %d\n", i, total);  /* attivalo per tracciare */
    }

    printf("Totale finale: %d\n", total);
    return 0;
}

Togli il commento dalla printf ed esegui di nuovo per vedere il ciclo costruire la sua risposta. Tracciare con le stampe non è elegante, ma in C è veloce e funziona sempre: un debugger ti dice di più, una printf ti dice qualcosa subito.

Due abitudini evitano che diventi un disastro. Cancella il codice commentato prima del commit; il controllo di versione ricorda la versione vecchia, così non devi farlo tu. E quando lasci di proposito una riga disattivata, spiega il perché in una nota accanto.

Commenti di documentazione

Un commento a blocco sopra una funzione è il posto dove spiegare cosa fa, cosa significano i suoi parametri e qualsiasi cosa sorprendente che la riguardi.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Converte una temperatura da gradi Celsius a gradi Fahrenheit.
 *
 *   c: la temperatura in ingresso, in Celsius
 *
 * Restituisce la temperatura equivalente in Fahrenheit.
 */
double celsius_to_fahrenheit(double c) {
    return c * 9.0 / 5.0 + 32.0;
}

int main(void) {
    printf("100C = %.1fF\n", celsius_to_fahrenheit(100.0));
    printf("0C   = %.1fF\n", celsius_to_fahrenheit(0.0));
    return 0;
}

Strumenti come Doxygen leggono commenti strutturati come questi e generano documentazione di riferimento. Lo stile proprio di Doxygen usa /** ... */ con i tag @param e @return:

/**
 * Converte Celsius in Fahrenheit.
 * @param c temperatura in Celsius
 * @return la stessa temperatura in Fahrenheit
 */
double celsius_to_fahrenheit(double c);

Per il tuo codice vanno bene entrambi. Quello che conta è che il commento stia accanto alla dichiarazione che le persone leggono, di solito nel file header, invece di essere sepolto nell'implementazione.

Cosa vale la pena commentare

La regola che sopravvive al contatto con le codebase reali: commenta il perché, non il cosa.

i++;  // incrementa i          <- non dice nulla che il codice non dicesse già

/* Salta il BOM: i file esportati dal vecchio sistema iniziano con
   tre byte che non fanno parte dei dati. */
offset += 3;

Il secondo commento contiene un'informazione che nel codice non c'è da nessuna parte. Il primo è rumore che prima o poi contraddirà la riga che descrive, perché i commenti non vengono aggiornati quando il codice cambia.

Cose che in C valgono davvero un commento:

• Chi possiede questa memoria. Se una funzione restituisce un puntatore che il chiamante deve liberare con free, dillo. Il C non ha modo di esprimerlo nel tipo.
• Unità e intervalli. int timeout; è ambiguo: secondi o millisecondi?
• Correttezza non ovvia. Perché il ciclo si ferma a n - 1, perché questo cast è sicuro, perché il buffer è di 256 byte.
• Stranezze volute. Il codice che sembra un bug ma non lo è attira "correzioni" da chi lo leggerà in futuro, a meno che non sia segnalato.

#include <stdio.h>
#include <string.h>

int main(void) {
    char name[32];  /* 31 caratteri più il '\0' finale */

    /* strncpy NON aggiunge un terminatore se la sorgente riempie il buffer,
       quindi lo scriviamo noi. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

    printf("Nome: %s\n", name);
    return 0;
}

Quel commento si guadagna il suo posto: la riga sotto sembra ridondante e non lo è.

I commenti dentro le stringhe non sono commenti

Un ultimo dettaglio. I marcatori di commento non hanno alcun significato speciale dentro una stringa letterale o una costante carattere:

#include <stdio.h>

int main(void) {
    printf("Avanzamento: 50%% // non e' un commento\n");
    printf("Il percorso e' /* solo testo */\n");
    return 0;
}

Entrambe le righe vengono stampate per intero. Il compilatore suddivide le stringhe in token prima di cercare i commenti, quindi // tra virgolette sono semplicemente due caratteri. (Il %% nella prima riga è il modo per stampare un simbolo di percentuale letterale con printf: % da solo inizia uno specificatore di formato.)