No cOMMENT
come E perché scrivere i commenti in C (e linguaggi c-like)
Dom Cobb: Ég hef allt undir stjórn Arthur: hið gagnstæða væri alvarlegt
Non so se avete visto lo splendido Inception di Christopher Nolan. Bene, provate a pensare come sarebbe vedere un film con una trama così complessa doppiato in una lingua che non conoscete, come l’islandese per esempio (e senza sottotitoli!). Ci capireste qualcosa? Cosa si dicono Dom Cobb e Arthur qua sotto? Ecco, i sottotitoli sono i commenti del Cinema…
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 codice 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, quest’ultimo è 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 quasi reale (solo quasi, eh!) che ho scritto alcuni anni fa: per questo esempio l’ho solo adattato un po’). 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(Dev *p)
{
int n=0;
if (p->msg[0]) {
snprintf(p->btx,sizeof(p->btx),"data: %s",p->msg);
if (!(n=(sdata(p->ch,(char*)p->btx,strlen(p->msg)))))
return -1;
p->msg[0]=0;
}
return n;
}
Come avrete notato non ci sono commenti, il codice è (a dir poco) criptico, e si risparmia su tutto: nomi, spazi, linee: non si sa mai che qualcuno riesca perfino a capire cosa c’è scritto. Per maniaci della segretezza.
Caso 2: codice auto-commentante
int sendMessageToDeviceA1(
DeviceA1 *p_deviceA1)
{
int number_sent = 0;
if (p_deviceA1->message_to_send[0]) {
snprintf(p_deviceA1->buffer_tx, sizeof(p_deviceA1->buffer_tx), "data: %s",
p_deviceA1->message_to_send);
if (!(number_sent = sendDeviceData(p_deviceA1->channel_tx,
(char *)p_deviceA1->buffer_tx,
strlen(p_deviceA1->buffer_tx))))
return -1;
p_deviceA1->message_to_send[0] = 0;
}
return number_sent;
}
Come avrete notato 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
/* NAME
* sendMsgDev - invia un messaggio al dispositivo
* SYNOPSIS
* int sendMsgDev(
* DevA1 *dev); // dispositivo destinazione
* DESCRIPTION
* Invia un messaggio al dispositivo di tipo A1. L'argomento <dev> è un pointer
* alla struttura dati del dispositivo.
* RETURN VALUE
* In caso di successo, sendMsgTo () restituirà il numero di caratteri inviati.
* Altrimenti, viene restituito -1.
*/
int sendMsgDev(
DevA1 *dev) // dispositivo destinazione
{
int n_sent = 0; // numero char spediti
// attendo il messaggio da spedire
if (dev->msg_2_snd[0]) {
// formatto il messaggio nel buffer di trasmissione
snprintf(dev->buf_tx, sizeof(dev->buf_tx), "data: %s", dev->msg_2_snd);
// spedisco il messaggio al dispositivo (ed esco in caso di errore)
if (!(n_sent = sendData(dev->chan_tx, (char *)dev->buf_tx, strlen(dev->buf_tx))))
return -1;
// messaggio spedito: reset contenuto
dev->msg_2_snd[0] = 0;
}
// esco con numero di char spediti
return n_sent;
}
Come avrete notato ci sono una intestazione (abbastanza completa, ma si può espandere) 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!
