Clean code/commentaires : le bon, la brute, le truand

Sous ce titre racoleur et dans la lignée du premier article qui parle du sujet « clean code : writing code for humans », je vous propose d’aborder le sujet des commentaires… Très souvent, cela déclenche un débat polémique interminable entre les pros et les antis… C’est comme ça dans notre noble métier, on s’ennuie tellement que quand l’occasion de troller se présente, bah on saute dessus.

Signal to noise ratio ?

Ce qui est important quand on aborde un sujet qui, « à priori », est sans grande valeur et ne mérite pas un blog-post, c’est de préciser notre objectif. Quelle est la finalité attendue ? En quoi les commentaires (ou l’absence de commentaires) m’aide à l’atteindre ?

Notre objectif ici est d’améliorer le ratio signal/bruit de notre code. Pour produire du code facilement compréhensible et accessible par tous, nous devons réduire au minimum tout ce qui ne porte pas d’information utile (le bruit) pour ne conserver que la partie utile (le signal) et donc éviter à notre petit cerveau d’avoir a faire le tri, en plus de comprendre le code de Michel.

Paradoxalement, les commentaires peuvent être considérés comme du bruit, voire parfois comme du vacarme… C’est ce que je vais tenter de vous montrer dans ce blog post. Après avoir lu pas mal de choses sur le sujet, je répertorie 3 catégories de commentaires : les bons, les brutes et les truands. Sans vouloir manquer de respect à ce monument du cinéma, je vous propose de les aborder dans le désordre.

La brute

Le plus courant des commentaires : celui qui n’apporte aucune valeur ajoutée mais qui est tellement simple à mettre, qu’on finit par en mettre des tonnes.

Pourquoi la brute ? Parce qu’il est bêtement ajouté en masse et sans nuance.

Prenons les exemples suivants :

Dans ces deux exemples, les commentaires ne servent à rien : la signature de la méthode et de la propriété sont parfaitement explicites et vous pouvez être certains qu’ils ne seront jamais lus.

Puis celui-ci :

Idem : les méthodes et les variables sont suffisamment bien nommées pour ne pas avoir à ajouter de commentaires.

Le truand

Celui-ci est très souvent une brute qui a mal tourné faute d’attention :

Ce type de commentaires ne colle pas avec le code et vous induit en erreur car on n’a pas maintenu son contenu en même temps que le code ! C’est également un effet de bord non négligeable : avoir des commentaires, c’est s’obliger à les maintenir (et donc encore plus de travail et moins de temps à troller à la machine à café). Si vous ne le faîtes pas, l’ensemble des développeurs n’auront plus confiance en eux et donc ne les liront plus… ce qui les rend tous inutiles (même les bons).

Le bon

Le code reste du code et parfois il est difficile – voire impossible- de faire passer toute l’information utile par lui : le choix d’un algorithme plutôt qu’un autre, celui de ne pas optimiser un bloc de code, de ne pas paralléliser des traitements alors, qu’a priori, c’est une bonne idée, etc. En général, tout ce qui touche à vos partis pris et aux choix que vous faîtes et qui ne semble pas naturel mérite un petit commentaire.

Lorsque vous développez des API, des Frameworks des services web (en gros, des façades), il est également utile de les documenter proprement voire d’expliciter le traitement interne lorsque celui-ci n’est pas disponible.

En conclusion

Un bon code est sa propre documentation. Si vous êtes sur le point d’en ajouter un, demandez-vous d’abord comment améliorer le code pour le rendre inutile. Il faut donc éviter les commentaires car le code doit être explicite et il convient de réserver les commentaires pour ce que le code ne peut pas exprimer. La plupart des autres types de commentaires doivent être considérés comme du bruit qui parasite votre code.