Regola
Funzioni senza commenti esplicativi.
Le funzioni prive di commenti risultano
difficili da comprendere per gli altri sviluppatori.
Linguaggi supportati: 45+Introduzione
Le funzioni senza commenti costringono gli sviluppatori a dedurre l'intento unicamente dai dettagli di implementazione. Questo rallenta le code review e rende la manutenzione più soggetta a errori. La mancanza di spiegazioni nasconde anche assunzioni relative alla validazione, alle aspettative di input o ai vincoli di sicurezza. Una documentazione chiara riduce l'uso improprio e aiuta i team a comprendere il comportamento del codice più rapidamente.
Perché è importante
Implicazioni sulla sicurezza: I commenti mancanti celano ipotesi relative alla validazione, ai controlli di autorizzazione e agli input attendibili, facilitando un uso improprio e aumentando i rischi per la sicurezza.
Impatto sulle prestazioni: Le funzioni non documentate potrebbero essere utilizzate in modo errato, causando operazioni onerose ripetute, parsing non necessari o una gestione inefficiente dei dati.
Manutenibilità: gli sviluppatori perdono più tempo a leggere e a fare il reverse engineering della logica quando l'intento non è documentato, rallentando il refactoring e l'inserimento di nuove risorse.
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é è errato: la funzione elabora campi legati alla sicurezza, ma non documenta le ipotesi su fonti attendibili, struttura prevista o 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 documenta l'intento, gli input previsti e i vincoli di sicurezza, rendendo l'utilizzo prevedibile e prevenendo integrazioni non sicure.
Conclusione
Aggiungi commenti chiari a qualsiasi funzione in cui l'intento, le ipotesi o i vincoli non siano ovvi dalla firma. Documenta ciò che la funzione si aspetta, cosa restituisce e qualsiasi comportamento rilevante per la sicurezza. Ciò migliora la qualità delle code review, riduce l'uso improprio e garantisce un comportamento prevedibile nell'intera codebase.
