Règle
fonctionnalités sans commentaires commentaires.
Fonctions sans commentaires sont difficiles à
comprendre pour autres développeurs.
Langues prises en charge : 45+Introduction
Les fonctions sans commentaires forcent les développeurs à déduire l'intention à partir des seuls détails d'implémentation. Cela ralentit les revues de code et rend la maintenance plus sujette aux erreurs. Les explications manquantes masquent également les hypothèses concernant la validation, les attentes d'entrée ou les contraintes de sécurité. Une documentation claire réduit les erreurs d'utilisation et aide les équipes à comprendre plus rapidement le comportement du code.
Pourquoi c'est important
Implications de sécurité : Les commentaires manquants masquent les hypothèses concernant la validation, les vérifications d'autorisation et les entrées fiables, facilitant ainsi les abus et augmentant les risques de sécurité.
Impact sur les performances : Les fonctions non documentées peuvent être utilisées de manière incorrecte, entraînant des opérations coûteuses répétées, une analyse inutile ou une gestion inefficace des données.
Maintenabilité : Les développeurs passent plus de temps à lire et à faire de la rétro-ingénierie logique lorsque l'intention n'est pas documentée, ce qui ralentit le refactoring et l'intégration.
Exemples de code
❌ 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')
};
}Pourquoi c'est incorrect : La fonction traite des champs pertinents pour la sécurité, mais ne documente pas les hypothèses concernant les sources fiables, la structure attendue ou les contraintes d'entrée.
✅ 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')
};
}Pourquoi c'est important : Le commentaire documente l'intention, les entrées attendues et les contraintes de sécurité, rendant l'utilisation prévisible et prévenant une intégration dangereuse.
Conclusion
Ajoutez des commentaires clairs à toute fonction dont l'intention, les hypothèses ou les contraintes ne sont pas évidentes à partir de la signature. Documentez ce que la fonction attend, ce qu'elle renvoie et tout comportement pertinent pour la sécurité. Cela améliore la qualité des revues, réduit les utilisations abusives et assure un comportement prévisible dans l'ensemble de la base de code.
