Suite à l’article de la semaine dernière sur les commentaires, je met une deuxième couche, avec d’autres arguments sur ce sujet.
Cet article est toujours tiré du livre 97 choses que tout programmeur devrait savoir, et Kevlin Henney partage son avis la-dessus.
Voici son avis :
La différence entre la théorie et la pratique est plus grande dans la pratique que dans la théorie : une observation qui s’applique certainement aux commentaires. En théorie, l’idée générale de commenter le code ressemble à une valeur digne : offrir le détail du lecteur, une explication de ce qui se passe. Quel pourrait être plus utile que d’être utile ? Dans la pratique, cependant, les commentaires deviennent souvent un problème. Comme pour toute autre forme d’écriture, il existe une compétence pour rédiger de bons commentaires. Une grande partie de la compétence consiste à savoir quand ne pas les écrire.
Lorsque le code est mal formé, les compilateurs, les interprètes et d’autres outils seront sûrs de s’opposer. Si le code est en quelque sorte fonctionnellement incorrect, les examens, les analyses statiques, les tests et l’utilisation quotidienne dans un environnement de production éliminent la plupart des erreurs. Mais qu’en est-il des commentaires ? Dans The Elements of Programming Style (Computing McGraw-Hill), Kernighan et Plauger notent que « un commentaire est nul (ou négatif) s’il est faux. » Et pourtant, de tels commentaires souvent lèvent et survivent dans une base de code d’une manière qui les erreurs de codage ne l’ont jamais pu. Ils fournissent une source constante de distraction et de désinformation, une subtile mais constante traînée sur la pensée d’un programmeur.
Qu’en est-il des commentaires qui ne sont pas techniquement faux, mais n’ajoute aucune valeur au code ? De tels commentaires sont du bruit. Ces commentaires, tel un perroquet du code, n’offrent rien d’extra au lecteur: en précisant quelque chose une fois dans le code et à nouveau dans un langage naturel, il ne le rend plus vrai ou plus réel. Le code commenté n’est pas un code exécutable, donc il n’a aucun effet utile pour le lecteur ou l’exécution. Il devient également très rapide. Les commentaires liés à la version et le code commenté essaient de répondre aux questions de version et d’historique. Ces questions ont déjà été répondu (beaucoup plus efficacement) par des outils de contrôle de version.
Une prévalence de commentaires bruyants et de commentaires incorrects dans une base de code encourage les programmeurs à ignorer tous les commentaires, soit en les ignorant soit en prenant des mesures actives pour les cacher. Les programmeurs sont ingénieux et enlèveront tout ce qui est perçu comme un dommage : replier des commentaires; changer le colorier pour que les commentaires et l’arrière-plan soient de la même couleur; scripts pour filtrer les commentaires. Pour sauvegarder une base de code à partir de telles mauvaises applications de l’ingéniosité du programmateur, et pour réduire le risque de négliger tout commentaire de valeur authentique, les commentaires devraient être traités comme s’il s’agissait d’un code. Chaque commentaire devrait ajouter de la valeur pour le lecteur, sinon il s’agit de déchets qui devraient être supprimés ou réécrits.
Qu’est-ce qui se qualifie alors en valeur ? Les commentaires doivent expliquer les choses que le code ne fait pas, et ne dit pas. Un commentaire expliquant ce qu’un code devrait déjà dire est une invitation à modifier la structure du code ou les conventions de codage afin que le code parle de lui-même. Au lieu de compenser la mauvaise méthode ou les noms de classe, renommez-les. Au lieu de commenter les sections dans de longues fonctions, extraire des fonctions plus petites dont les noms capturent l’intention des premières sections. Essayez d’exprimer autant que possible par code. Tout manque à gagner entre ce que vous pouvez exprimer en code et ce que vous souhaitez exprimer au total devient un candidat plausible pour un commentaire utile. Commenter ce que le code ne peut pas dire, pas simplement ce qu’il ne dit pas.
