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

clip_image002

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 ?

clip_image004

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 :

clip_image006

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 :

clip_image008

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 :

clip_image010

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.

2 Commentaires Laisser un commentaire

Mon premier réflexe quand je tombe sur un code commenté, c’est de les effacer complètement et de refactorer le code pour que ce soit aussi explicite que de la prose anglaise.

Pour celà, une super pratique consiste à TOUJOURS pratiquer le « extract till you drop »: https://sites.google.com/site/unclebobconsultingllc/home/articles/one-thing-extract-till-you-drop

Vous verrez qu’avec cette pratique, vous aurez l’impression de lire un livre, plutôt qu’un code 😉

N’ayez pas peur des noms de méthodes longs pour les méthodes privées de vos classes: elles agissent en tant que commentaire !
Rappelez-vous: un commentaire n’est jamais fiable, jamais.
Splitter votre code en petites méthodes bien nommées et privées font unité avec votre code source, et est donc fiable.

Je la pratique depuis 3 ans et c’est un plaisir.

Répondre
Rénald VENANT-VALERY
janvier 27, 2015 21:50

Je fais partie des malheureux qui n’arrivent jamais à me relire, je ne peux donc qu’abonder dans le sens de cet article. L’excès de commentaires est un véritable frein à l’appropriation du code par d’autres. A mon niveau, je les utilise principalement pour expliquer les risques d’un refactoring et pourquoi j’ai pu choisir de dupliquer du code… toutefois, je me sens de plus en plus incité à écrire ces petites choses dans un fichier readme.txt en évidence à la racine du folder…

Répondre

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *