Règle

Commentaire sur le objectif (pourquoi), pas la mécanique (quoi).
Commentaires que simplement reformuler ce le code fait 
fournit aucun valeur valeur et peut devenir obsolète.

Langues prises en charge : 45+

Introduction

Les commentaires qui reformulent ce que le code fait n'apportent aucune clarté supplémentaire et sont souvent désynchronisés avec l'implémentation. Lorsque les commentaires divergent du code, ils introduisent de la confusion et ralentissent les revues. Les commentaires utiles expliquent l'intention, les hypothèses et le raisonnement derrière les décisions. Cela rend la logique complexe plus facile à comprendre et à maintenir.

Pourquoi c'est important

Implications de sécurité : Les commentaires basés sur l'intention révèlent des hypothèses concernant la validation, la confiance dans les entrées ou le contrôle d'accès qui pourraient ne pas être visibles dans l'implémentation.

Impact sur les performances: Les commentaires qui clarifient les décisions liées aux performances aident à éviter les optimisations accidentelles ou les changements qui altèrent les caractéristiques de performance attendues.

Maintenabilité du code : Les commentaires axés sur l'intention aident les développeurs à comprendre la raison d'être d'un morceau de code, réduisant ainsi le temps nécessaire pour le modifier ou l'auditer.

Surface d'attaque : Des commentaires clairs réduisent le risque de mauvaise utilisation des fonctions internes de manière à introduire un comportement dangereux ou à étendre la surface d'attaque.

Exemples de code

❌ Non conforme :

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

Pourquoi c'est incorrect : Ces commentaires répètent ce que le code montre déjà, sans fournir de contexte sur l'intention ou les contraintes.

✅ 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();
}

Pourquoi c'est important : Le commentaire explique pourquoi la normalisation est requise, clarifiant l'intention et prévenant un refactoring incorrect.

Conclusion

Rédigez des commentaires qui expliquent pourquoi le code est nécessaire, et non ce que chaque ligne montre déjà. Décrivez les hypothèses, les contraintes et le raisonnement lorsqu'ils ne sont pas évidents à partir de l'implémentation. Cela crée une documentation maintenable qui reste utile même lorsque le code évolue.