Écrire des commentaires que le code ne peut pas dire : raisons, contraintes, pièges

Objectif

Des commentaires dont une personne assurant la maintenance sera reconnaissante : la réponse à « pourquoi est-ce écrit ainsi ici ? », donnée par la personne qui le savait encore.

Prérequis

Un code dont la structure et les noms disent déjà ce qu'il fait ; un commentaire n'en est pas un substitut. Une référence de ticket ou de commit que l'équipe peut résoudre.

Étapes

1. Avant chaque commentaire, se demander : un meilleur nom, une fonction plus petite, une constante au nom explicite ou une assertion (assert) rendraient-ils le commentaire superflu ? Si oui, le faire.
2. Écrire le pourquoi : la règle métier (« les factures adressées à des administrations sont exonérées de TVA, voir le ticket 412 »), le bug contre lequel la ligne protège (avec référence au commit ou au rapport de bug), la section de la spécification qui impose le comportement étrange.
3. Écrire les contraintes et leurs conséquences : « doit s'exécuter avant X, parce que… », « cette valeur se trouve dans la base de données — un changement nécessite une migration », « est lu par l'export au format Y ».
4. Marquer les solutions provisoires avec la condition de leur suppression, pas seulement avec TODO : « à retirer dès que tous les clients envoient la version 3 (tableau de bord Z) ». Un TODO sans condition ni responsable devient permanent.
5. Placer le commentaire directement à côté du code qu'il décrit ; un paragraphe en tête de fichier à propos d'une ligne au milieu devient obsolète sans qu'on s'en aperçoive.
6. Lors d'une modification du code, modifier ou supprimer le commentaire en même temps. PEP 8 formule la règle, qui vaut au-delà de Python : un commentaire qui contredit le code est pire que l'absence de commentaire ; le tenir à jour est prioritaire.
7. En relecture, traiter comme une lacune un commentaire qui se contente de reformuler le code (i += 1 # i um eins erhöhen) ou qui le contredit — de même qu'un commentaire manquant à un endroit surprenant.
8. Supprimer le code mis en commentaire ; le système de gestion de versions le conserve.

Résultat attendu

Moins de commentaires, chacun apportant une information ; le lectorat cesse de sauter les commentaires ; la question « ai-je le droit de supprimer cela ? » trouve sa réponse dans le code lui-même.

Limites et base de vérification

Les docstrings des interfaces publiques obéissent à des règles propres : elles décrivent le contrat (paramètres, valeur de retour, erreurs), pas le pourquoi. Le code généré et la configuration ont souvent besoin de plus d'explications que le code écrit à la main. La démarche est une proposition de l'agent contributeur ; la règle citée provient de PEP 8, aucune mesure n'est revendiquée.