Regola
Funzioni senza commenti commenti esplicativi.
Funzioni senza commenti sono difficili da
capire per altri sviluppatori.
Linguaggi supportati: 45+Introduzione
Le funzioni prive di commenti costringono gli sviluppatori a dedurre l'intento solo dai dettagli di implementazione. Ciò rallenta le revisioni del codice e rende la manutenzione più soggetta a errori. La mancanza di spiegazioni nasconde inoltre i presupposti relativi alla convalida, alle aspettative sugli input o ai vincoli di sicurezza. Una documentazione chiara riduce gli errori di utilizzo e aiuta i team a comprendere più rapidamente il comportamento del codice.
Perché è importante
Implicazioni per la sicurezza: l'assenza di commenti nasconde i presupposti relativi alla convalida, ai controlli di autorizzazione e agli input attendibili, facilitando gli abusi e aumentando i rischi per la sicurezza.
Impatto sulle prestazioni: le funzioni non documentate potrebbero essere utilizzate in modo errato, causando operazioni ripetute e dispendiose, analisi sintattiche superflue o una gestione inefficiente dei dati.
Manutenibilità: quando l'intento non è documentato, gli sviluppatori dedicano più tempo alla lettura e al reverse engineering della logica, rallentando il refactoring e l'inserimento dei nuovi collaboratori.
Esempi di codice
❌ Non conforme:
// No explanation of expected input or security assumptions
function normalizeUser(user) {
if (!user || typeof user !== 'object') return null;
return {
id: String(user.id).trim(),
email: user.email.toLowerCase(),
roles: user.roles.filter(r => r !== 'guest')
};
}Perché è sbagliato: la funzione elabora campi rilevanti per la sicurezza, ma non documenta i presupposti relativi alle fonti attendibili, alla struttura prevista o ai vincoli di input.
✅ Conforme:
/**
* Normalize user data from external input.
* Expects: `user` contains `id`, `email`, and `roles`.
* Rejects invalid structures and filters unsafe role values.
* Ensures normalized identifiers and lowercased email for consistency.
*/
function normalizeUser(user) {
if (!user || typeof user !== 'object') return null;
return {
id: String(user.id).trim(),
email: user.email.toLowerCase(),
roles: user.roles.filter(r => r !== 'guest')
};
}Perché è importante: il commento descrive lo scopo, i dati di input previsti e i vincoli di sicurezza, rendendo l'utilizzo prevedibile e impedendo un'integrazione non sicura.
Conclusione
Aggiungere commenti chiari a qualsiasi funzione in cui l'intento, i presupposti o i vincoli non risultino evidenti dalla firma. Documentare ciò che la funzione si aspetta, ciò che restituisce ed eventuali comportamenti rilevanti ai fini della sicurezza. Ciò migliora la qualità della revisione, riduce gli errori di utilizzo e garantisce un comportamento prevedibile in tutto il codice.
