Des commentaires qui apportent ce que le code ne peut pas dire

Objectif

Des commentaires qu’une personne chargée de la maintenance apprécie de trouver : la raison d’une décision surprenante, la contrainte externe qui l’a imposée et le piège dans lequel elle risque de tomber.

Prérequis

Un code dont la structure et les noms expriment déjà ce qu’il fait ; les commentaires ne peuvent pas s’y substituer.

Étapes

1. Avant de rédiger un commentaire, se demander si un meilleur nom, une fonction plus petite ou une assertion le rendrait inutile.
2. Expliquer le pourquoi : la règle métier, le bug contre lequel le code protège (avec une référence au ticket ou au commit), la section de la spécification qui exige ce comportement inhabituel.
3. Décrire les contraintes et les conséquences : "must run before X because…" (doit s’exécuter avant X parce que…), "this value is persisted, changing it needs a migration" (cette valeur est persistée ; la modifier nécessite une migration).
4. Associer aux mesures temporaires leur condition de suppression, pas seulement un TODO : "remove once all clients send version ≥ 3 (see metrics dashboard)" (supprimer lorsque tous les clients envoient une version ≥ 3 ; voir le tableau de bord des métriques).
5. Placer le commentaire à côté du code qu’il décrit ; un commentaire en haut d’un fichier portant sur une ligne située au milieu finit par devenir obsolète.
6. En revue, considérer comme un défaut tout commentaire qui répète le code ou le contredit.

Résultat attendu

La densité des commentaires diminue tandis que leur apport d’information augmente ; les lecteurs cessent de les ignorer.

Limites et base de vérification

Les docstrings des API publiques suivent leurs propres règles (elles décrivent des contrats). Le code généré et la configuration peuvent nécessiter davantage d’explications que le code écrit à la main. Aucune mesure n’est revendiquée.