Commenti sul codice: suggerimenti e best practises

I programmi devono essere scritti in modo che la gente li possa leggere e soltanto incidentalmente che siano eseguiti dalle macchine, Hal Abelson

Il noto professore del MIT con questa affermazione potrebbe aver volutamente sottovalutato l'importanza dell'esecuzione del codice, ma di certo ha centrato il fatto che i programmi hanno due tipi di lettori molto diversi tra loro: i compilatori (le macchine) e i lettori umani. I primi ignorano completamente i commenti trovando sintatticamente corretto e comprensibile qualsiasi programma. Per i secondi la situazioni è più complessa: alcuni programmi possono risultare più difficili da capire è si ricorre allo strumento dei commenti per a dare loro un senso.

Esistono innumerevoli risorse sia online che offline sul come scrivere codice pulito e leggibile, ma non è altrettanto generosa la letteratura dedicata ai commenti. Questa scarsità è causata (in parte) dal fatto che risulta difficile misurare la qualità di qualcosa di personale. Che parametri utilizzare per valutare lo stile e la chiarezza di qualcosa di soggettivo come un commento? Eppure nonostante queste avversità è ampiamente diffusa tra gli addetti ai lavori l'idea che un commento scritto male sia di gran lunga peggio che trovarsi di fronte a righe di codice non commentate affatto.

Peter Vogel una volta scrisse:

1. Scrivere e manutenere i commenti è una spesa.
2. Il compilatore non controlla i commenti, quindi non è possibile determinarne la correttezza
3. D'altra parte, hai la garanzia che il computer sta facendo esattamente ciò che il tuo codice gli sta dicendo.

Anche se tutti e tre i punti sono giusti, sarebbe un errore interpretarli alla lettera e cadere nella situazione opposta, quella del non scrivere mai nessun tipo di commento.

5 regole da seguire per migliorare la scrittura dei commenti:

• Regola 1: I commenti non devono duplicare il codice.
• Regola 2: I buoni commenti non giustificano il codice poco chiaro.
• Regola 3: Servono troppi commenti? Forse c'è un problema nel codice..
• Regola 4: Aggiungi commenti nelle correzioni dei bug.
• Regola 5: Utilizzare i commenti per contrassegnare le implementazioni incomplete.

Vediamo nel dettaglio ciascuna di queste regole, con degli esempi pratici.

Regola 1: I commenti non devono duplicare il codice.

Molti programmatori junior scrivono troppi commenti perché hanno imparato dai loro docenti. Ci si può ritrovare di fronte a situazioni in cui si aggiungere un commento a ogni parentesi graffa chiusa per indicare quale blocco sta finendo:

if (x > 3) {
 … 
} // if

Una leggenda metropolitana vuole che gli insegnanti chiedano agli studenti di commentare ogni riga di codice. Sebbene questa pratica possa essere considerata accettabile per i programmatori alle prime armi, questo uso dei commenti è come imparare ad andare in bicicletta con le rotelle, aiuto che poi dovrà essere rimosso da grandi. Non sarebbe meglio imparare fin da subito senza?

I commenti che non aggiungono informazioni rilevanti hanno valore negativo perché:

• disturbano la vista
• necessitano del tempo per scriverli e leggerli
• possono diventare obsoleti

Un altro esempio : i = i + 1; // Aggiunge uno a i Queto commento è INUTILE , comporta solo un costo di manutenzione e si presta (giustamente!) a essere ridicolizzato su Reddit:

// crea un loop for // <-- commento
for // inizio del loop
(   // parentesi tonda
    // nuova linea
int // dichiarazione di tipo
i    // name per la dichiarazione
=   // operatore di assegnazione per la dichiarazione del ciclo for
0   // valore iniziale per i

Regola 2: I buoni commenti non giustificano il codice poco chiaro.

Un altro uso improprio dei commenti è quello di utilizzarli per fornire informazioni che avrebbero potuto essere inserite nel codice. Un caso tipico è nominare una variabile con una singola lettera per poi aggiunge un commento che ne descrive lo scopo:

private static Node getBestChildNode(Node node) {
    Node n; // miglior candidato per nodo figlio
    for (Node node: node.getChildren()) {
        // aggiorna n se lo stato corrente è migliore
        if (n == null || utility(node) > utility(n)) {
            n = node;
        }
    }
    return n;
}

Nomi di variabili più parlanti eliminano il problema:

private static Node getBestChildNode(Node node) {
    Node bestNode;
    for (Node currentNode: node.getChildren()) {
        if (bestNode == null || utility(currentNode) > utility(bestNode)) {
            bestNode = currentNode;
        }
    }
    return bestNode;
}

Come scrissero Kernighan e Plauger in The Elements of Programming Style (Gli elementi dello stile di programmazione), "Non commentare il codice errato, riscrivilo". https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style

Regola 3: Servono troppi commenti? Forse c'è un problema nel codice.

Il commento più aspro nel codice sorgente Unix è "Non ci aspettiamo che tu lo capisca", che appare prima di un codice intricato per il cambio di contesto. Dennis Ritchie, in seguito ha spiegato che era inteso "nello spirito di 'Questo non sarà all'esame', piuttosto che come una sfida sfacciata". Sfortunatamente, si è scoperto che sia lui che il coautore Ken Thompson non l'hanno capito loro stessi e in seguito hanno dovuto riscriverlo!

Questo fa venire in mente la legge di Kernighan

Il debug è due volte più difficile che scrivere il codice. Pertanto il consiglio furbo (cit.) è quello di scrivere codice nel modo più intelligente possibile, se non si è abbastanza bravi nell'eseguirne il debug. Se scatta la necessità di commentare spesso è come ammettere di fare qualcosa di illegale. Si riesce a spiegare quanto è stato scritto? Bene. In caso contrario, riscrivere.

Regola 4: Aggiungi commenti nelle correzioni dei bug.

I commenti dovrebbero essere aggiunti non solo durante la scrittura iniziale del codice, ma anche durante la modifica, in particolare per correggere i bug. Consideriamo questo commento:

  // NOTA: almeno in Firefox 2, se l'utente trascina fuori dalla finestra del browser,
   // gli eventi di spostamento del mouse (mouse-move e mouse-down) non verranno scatenati fino quando
   // l'utente torna indietro all'interno della finestra. Una soluzione per questo problema
   // risiede nell'implementazione di onMouseLeave().
  @Override
  public void onMouseMove(Widget sender, int x, int y) { .. }

Il commento non solo aiuta il lettore a comprendere il codice nei metodi di riferimento correnti, ma è anche utile per determinare se il codice è ancora necessario e come testarlo.

Regola 5: Utilizzare i commenti per contrassegnare le implementazioni incomplete.

A volte è necessario archiviare il codice anche se presenta limitazioni note. Sebbene si possa essere tentati di non condividere le carenze note nel proprio codice, è meglio renderle esplicite, ad esempio con un commento TODO:

// TODO: stiamo facendo in modo che il separatore decimale sia il punto,
// indipendentemente dalle impostazioni internazionali del telefono. Abbiamo bisogno di pensare
// come consentire la virgola come separatore decimale, che richiederà
// aggiornamento del parsing dei numeri e altri punti che trasformano i numeri
// in stringhe, come FormatAsDecimal

L'utilizzo di un formato standard per tali commenti aiuta a valutare e affrontare il problema tecnico. Meglio ancora, aggiungi un issue al tuo tracker e fai riferimento all’issue nel tuo commento.

Il codice ti dice come, i commenti ti dicono il perché

Citanto Jeff Atwood,co-fondatore di StackOverflow possiamo concludere affermando che seguire queste regole dovrebbe far risparmiare tempo e frustrazione ai team di sviluppo.

Quali altri suggerimenti vi vengono in mente? Non vediamo l'ora di leggerli (guarda un po') nella sezione dei commenti dei nostro profilo Linkedin

Fonti dell'articolo: https://stackoverflow.blog https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/