Nei titoli e nei testi troverete qualche rimando cinematografico (ebbene si, sono un cinefilo). Se non vi interessano fate finta di non vederli, già che non sono fondamentali per la comprensione dei post...

Di questo blog ho mandato avanti, fino a Settembre 2018, anche una versione in Spagnolo. Potete trovarla su El arte de la programación en C. Buona lettura.

giovedì 23 agosto 2012

No Comment
come scrivere i commenti nel C

Se siete di quelli che "Non scrivo commenti. Sono una perdita di tempo" fermatevi qui. Tanto non riuscirei a convincervi (e neanche ci tengo).

Per tutti gli altri: il commento è un vostro amico fedele, non vi abbandonerà mai. Il commento è l'ultima barriera tra il capire e il non capire "cosa avevo in testa quando ho scritto quel programma un anno fa ?". Il commento è la vostra dimostrazione di rispetto per i colleghi di lavoro: prima o poi, qualcuno di loro metterà le mani sul vostro Software, e il numero di maledizioni che vi manderà sarà inversamente proporzionale al numero (e alla qualità) dei commenti che avete scritto.

Certo, ci sono varie maniere di commentare il codice: si va dal "Absolute No Comment" al "auto-commentante con aggiunta di commenti" (beh, questo è un po' esagerato...), con tutte le sfumature intermedie possibili...

Facciamo una piccola dimostrazione: esaminiamo tre maniere si scrivere una funzione di lettura di un dispositivo di controllo industriale (si tratta, nel Caso 3, di codice reale che ho scritto alcuni anni fa: per questo esempio ho solo cambiato alcuni nomi). Si noti che i tre codici sono praticamente identici, anche se la lettura da tutt'altra impressione...

Caso 1: codice Absolute No Comment

int smsg(S_dev *p)
{
    if (p->msg) {
        p->btx[0]=p->msg;
        if (!sndch(p->ch,(char *)p->btx,(size_t)1))
            return(-1);
        p->msg=0;
    }
    return(0);
}


come noterete non ci sono commenti, il codice è (a dir poco) criptico, e si risparmia su tutto: nomi, spazi, linee: non si sa mai che qualcuno potrebbe capire cosa c'è scritto. Per maniaci della segretezza.

Caso 2: codice auto-commentante

int sendMessageToDevDummy(
    S_dev_dummy *p_devdum)
{
    if (p_devdum->msg_to_send != 0) {
        p_devdum->buffer_tx[0] = p_devdum->msg_to_send;

        if (!send_char_to_dev(p_devdum->channel_tx, (char*)p_devdum->buffer_tx, (size_t)1))
            return(-1);

        p_devdum->msg_to_send = 0;
    }

    return(0);
}


come noterete non ci sono commenti, ma il codice è auto-esplicativo e non si va al risparmio. I nomi sono scelti per la massima chiarezza. Per chi non ama i commenti ma vuole essere chiaro a tutti i costi.

Caso 3: codice chiaro e commentato

/* sendMessage()
 * invia un messaggio al dispositivo dummy
 */
int sendMessage(
    S_dev_dummy *dev)
{
    // attendo i messaggi da spedire
    if (dev->msg_2snd) {
        // copio il messaggio nel buffer di trasmissione
        dev->buf_tx[0] = dev->msg_2snd;

        // spedisco il messaggio
        if (! send_char_2dev(dev->chan_tx, (char *)dev->buf_tx, (size_t)1))
            return(-1);

        // libero il semaforo di trasmissione
        dev->msg_2snd = 0;
    }

    return(0);
}


come noterete ci sono una intestazione (che si dovrebbe espandere per le funzioni importanti) e molti brevi commenti. Il codice non è auto-esplicativo ma è sufficientemente chiaro. Per comment-lovers.

Inutile dirlo: io appartengo alla scuola comment-lovers. Però rispetto anche i seguaci del codice auto-commentante. Sui signori del Absolute No Comment l'unica cosa che posso dire è... No Comment. Comunque, se vi può interessare, il Caso 1 non è una forzatura, e ho visto anche di peggio, non fatemi parlare...

Ciao e al prossimo post.

Nessun commento:

Posta un commento