Regola
Commenta l'obiettivo (perché), non la meccanica (cosa).
I commenti che ripetono semplicemente ciò che fa il codice
non offrono alcun valore aggiunto e possono diventare obsoleti.
Linguaggi supportati: 45+Introduzione
I commenti che ripetono ciò che fa il codice non offrono alcuna chiarezza aggiuntiva e spesso finiscono per non essere allineati con l'implementazione. Quando i commenti divergono dal codice, introducono confusione e rallentano le revisioni. I commenti utili spiegano l'intento, le ipotesi e il ragionamento dietro le decisioni. Questo rende la logica complessa più facile da comprendere e mantenere.
Perché è importante
Implicazioni sulla sicurezza: I commenti basati sull'intento espongono supposizioni relative alla validazione, all'attendibilità degli input o al controllo degli accessi che potrebbero non essere visibili nell'implementazione.
Impatto sulle prestazioni: I commenti che chiariscono le decisioni relative alle prestazioni aiutano ad evitare ottimizzazioni accidentali o modifiche che alterano le caratteristiche di performance attese.
Manutenibilità del codice: I commenti incentrati sull'intento aiutano gli sviluppatori a comprendere il motivo per cui esiste una porzione di codice, riducendo il tempo necessario per modificarla o verificarla.
Superficie di attacco: Commenti chiari riducono la probabilità di utilizzare impropriamente le funzioni interne in modi che introducono comportamenti non sicuri o espandono 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é è errato: Questi commenti ripetono ciò che il codice mostra già, senza fornire alcun contesto su intenti o 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é la normalizzazione è necessaria, chiarendo l'intento ed evitando refactoring errati.
Conclusione
Scrivi commenti che spieghino perché il codice è necessario, non cosa mostra già ogni singola riga. Descrivi ipotesi, vincoli e ragionamenti quando non sono ovvi dall'implementazione. Questo crea una documentazione manutenibile che rimane utile anche quando il codice si evolve.
