Come scrivere commenti che spieghino l'intento invece di ripetere i meccanismi del codice

Regola

Commento su l' obiettivo (perché), non la modalità (cosa).
Commenti che si limitano a ripetono ciò il codice fornisce 
non non ulteriori valore e possono diventare obsoleto.

Lingue supportate: 45+

Introduzione

I commenti che si limitano a ripetere ciò che fa il codice non apportano ulteriore chiarezza e spesso non sono più in sintonia con l'implementazione. Quando i commenti divergono dal codice, creano confusione e rallentano le revisioni. I commenti utili spiegano l'intento, i presupposti e il ragionamento alla base delle decisioni. Ciò rende la logica complessa più facile da comprendere e da mantenere.

Perché è importante

Implicazioni per la sicurezza: i commenti basati sull’intento mettono in luce presupposti relativi alla convalida, all’affidabilità degli input o al controllo degli accessi che potrebbero non essere evidenti nell’implementazione.

Impatto sulle prestazioni: i commenti che chiariscono le decisioni relative alle prestazioni aiutano a evitare ottimizzazioni accidentali o modifiche che compromettono le caratteristiche prestazionali previste.

Manutenibilità del codice: i commenti incentrati sull'intento aiutano gli sviluppatori a comprendere il motivo per cui un determinato frammento di codice è stato inserito, riducendo il tempo necessario per modificarlo o verificarlo.

Superficie di attacco: commenti chiari riducono il rischio di un uso improprio delle funzioni interne che possa causare comportamenti non sicuri o ampliare la superficie di attacco.

Esempi di codice

❌ Non conforme:

// Loop through users
for (const user of users) {
    // Convert email to lowercase
    user.email = user.email.toLowerCase();
}

Perché è sbagliato: questi commenti ripetono ciò che il codice mostra già, senza fornire alcun contesto riguardo alle intenzioni o ai vincoli.

✅ Conforme:

/**
 * Normalize user emails so downstream permission checks
 * compare consistent lowercase values. Required because
 * external systems may send mixed-case emails.
 */
for (const user of users) {
    user.email = user.email.toLowerCase();
}

Perché è importante: il commento spiega perché è necessaria la normalizzazione, chiarendo l'intento ed evitando una rifattorizzazione errata.

Conclusione

Scrivi commenti che spieghino perché il codice è necessario, non ciò che ogni riga mostra già di per sé. Descrivi i presupposti, i vincoli e il ragionamento quando non risultano evidenti dall'implementazione. In questo modo si crea una documentazione facilmente gestibile che rimane utile anche quando il codice si evolve.