Ouarzy's Blog

 (Image tirée de Coder proprement -Robert C. Martin- édition Pearson 2009)

Cet article fait écho à un article d’Antoine du blog crafting labs.

Je me permets simplement d’en remettre une couche sur le sujet pour parler de mon expérience de commenteur repenti.

En effet, j’ai d’abord eu l’expérience d’un prof très insistant sur la nécessité de commenter son code. Et dans le milieu scolaire on peut difficilement lui donner tort, on travaille avec des personnes de niveaux très disparates, qui ne savent pas forcément lire du code.

 
Par la suite j’ai eu à travailler en C++ sur des algorithmes extrêmement techniques, utilisés dans un cadre pur R&D, et d'ailleurs souvent codé par des chercheurs plutôt que des informaticiens.
De fait, l’absence de commentaires était une plaie, car la complexité scientifique des traitements auraient vraiment méritée des explications.

Alors par “réflexe”, je me suis mis à commenter mon code abondamment, en me disant que n’importe qui (même mon commercial à la limite) devait être capable de comprendre mon code. Et puis après tout, plus il y’a de commentaires, plus c’est clair, donc mieux c’est non?

Avec le temps, le code évolue (par des collègues ou moi-même), et déjà je me rends compte que de nombreux blocs de commentaires n’ont plus de sens, ou (pire) ce sont simplement retrouvés là par copié/collé, mais désormais complètement hors contexte.

Qu’à cela ne tienne, de mon point de vue le problème c’était nous et notre façon de travailler, pas les commentaires! Je suis donc devenu d’autant plus exigeant en terme de commentaires, je me suis mis à les vérifier systématiquement, ainsi que ceux laissés par mes collègues.

Cela a (un peu) amélioré les choses, mais obligé de constater 1 an plus tard que même avec un énorme effort de maintien des commentaires, on se retrouve souvent avec des blocs incompréhensibles et/ou hors contexte. J’étais alors à la recherche de nouvelles solutions pour gérer ce problème récurrent.

C’est à cette période qu'on m'a conseillé la lecture de Clean Code (Robert C. Martin)

Et j’ai été interloqué par le chapitre sur les commentaires:
“Les commentaires ne sont pas comme la liste de Schindler. Ils ne représentent pas le "bien parfait". Les commentaires sont, au mieux, un mal nécessaire. Si nos langages de programmation étaient suffisamment expressifs ou si nous avions suffisamment de talent pour les manier de manière à exprimer nos intentions, nous n’aurions pas souvent besoin des commentaires, voire jamais.”

Si j’ai bien compris, soit le C# n’est pas suffisamment expressif, soit ...Je n’ai pas assez de talent pour le manier en exprimant mes intentions.
Je me suis d’abord offusqué, “C’est surtout plus facile pour les fainéants de se dire qu’il ne faut pas de commentaires!” (Oui c’est toujours le moment où on commence à comprendre qu’on a tort qu’on a le plus de mauvaise foi.)

Mais j’ai quand même appliqué le conseil de l’oncle Bob: “Par conséquent, lorsque vous éprouvez le besoin d’écrire un commentaire, réfléchissez et essayez de trouver une solution pour exprimer vos intentions avec du code”

Et la révélation a été immédiate: le fainéant c’était moi. En effet, il est bien plus simple de pondre une tartine de commentaire plutôt que de se retourner le cerveau à nommer/déplacer les fonctions de façon suffisamment intelligente pour qu’elles soient naturellement compréhensibles par un autre développeur.

Au final, alors que je passe désormais 75% de mon temps à refactorer mon code, je dois écrire à peine 10 lignes de commentaires par semaine. Principalement pour les API et les traitements d’images un peu complexe.
Et honnêtement, avec un peu de pratique, la différence est flagrante. Je n’ai jamais navigué avec autant de facilité dans mon code. Et je n’ai jamais eu aussi peu d’explications à donner quand un collègue travail sur mon code.

Tout ça pour dire: un code propre n’a quasi pas besoin de commentaires. Il doit se lire comme un livre (d’informaticien, certes). Un code abondamment commenté est avant tout le symptôme d’un code incompréhensible.
Les commentaires doivent être la rare exception (API publique, traitement scientifiquement complexe), et en aucun cas la règle.

Attention cela dit, les mauvais commentaires doivent être remplacés par du bon code. Et le simple fait de peu commenter ne produit pas automatiquement du bon code, cela va sans dire. Il n’y aurait rien de pire que du mauvais code qui ne serait pas commenté!

Le commentaire tue, mangez du (bon) code.