Article complet: Les commentaires traduisent notre échec à nous exprimer !

Discussion intéressante ce 11 février lors du troisième dojo du Club Agile Rhône Alpes : nous nous apprêtions à introduire des commentaires dans notre code de test quand un participant a fait remarquer qu'il préférerait voir ces mêmes informations sur la trace de sortie, afin de rendre les résultats de tests unitaires plus lisibles. Plusieurs solutions ont été discutées, et nous avons retenu la plus simple, à savoir inclure l'information en question directement dans le nom de la méthode de test.

Cela m'a fait prendre conscience à quel point un commentaire représente une information "morte" par rapport au code, "vivant" car exécuté. Et cela m'a remis en mémoire un chapitre du livre Clean Code: A Handbook of Agile Software Craftsmanship par Robert C. Martin (et d'autres auteurs comme Michael Feathers qui a écrit le chapitre "Error Handling"). En effet ce nouveau manuel de référence consacre pas moins de 21 pages à la question des commentaires dans le code (presqu'autant qu'au TDD !).

Comment bien commenter son code est un sujet assez sensible, sur lequel les développeurs et leurs managers sont enclins à s'enflammer facilement ! Personnellement je converge petit à petit vers l'opinion qu'il faut éviter les commentaires autant que possible, et Robert C. Martin explique cela très bien, aussi je traduis ci-dessous quelques extraits :

[Suite:]

En effet, les commentaires sont, au mieux, un mal nécessaire. Si nos langages de programmation étaient suffisamment expressifs, ou si nous avions le talent de les manier subtilement pour exprimer notre intention, nous n'aurions pas beaucoup besoin de commentaires - peut-être même pas du tout besoin.

Le bon usage des commentaires est de compenser notre échec à nous exprimer nous-mêmes avec du code. Notez que j'ai utilisé le mot échec. Je le pense vraiment. Les commentaires sont toujours des échecs. Nous devons en avoir parce que nous n'arrivons pas toujours à nous exprimer sans eux, mais leur utilisation n'est pas une cause de célébration.

Alors quand vous vous trouvez dans une situation ou vous devez écrire un commentaire, réfléchissez-y et regardez s'il n'y a pas un moyen de changer les circonstances, et de vous exprimer avec du code. Chaque fois que vous vous exprimez avec du code, vous devriez vous taper sur l'épaule. Chaque fois que vous écrivez un commentaire, vous devriez faire la grimace et ressentir l'échec de vos capacités d'expression.

Pourquoi suis-je si remonté contre les commentaires ? Parce qu'ils mentent. Pas toujours, et pas intentionnellement, mais trop souvent. Plus un commentaire est ancien, et plus loin il est du code qu'il décrit, plus il est probable qu'il soit tout simplement faux. La raison est simple. Les programmeurs ne peuvent pas raisonnablement les maintenir.

...

Il y a l'argument que les programmeurs devraient être suffisamment disciplinés pour garder les commentaires dans un état élevé de réparation, pertinence et précision. Je suis d'accord, ils devraient. Mais je préférerais que cette énergie aille dans la direction de rendre le code si clair et expressif qu'il n'ait plus besoin de commentaires du tout.

Des commentaires imprécis sont bien pires que pas de commentaires du tout. Ils sont malhonnêtes et vous trompent. Ils font des promesses qui ne seront jamais satisfaites. Ils exposent de vieille règles qui n'ont plus besoin d'être suivies (et qui ne devraient pas être suivies).

La vérité peut être trouvée à un seul endroit : le code. Seul le code peut véritablement vous dire ce qu'il fait. C'est la seule source d'information réellement précise. Par conséquent, bien que les commentaires soient quelquefois nécessaires, nous dépenserons une énergie significative à les minimiser.

Le chapitre continue ensuite avec de nombreux exemples de bons et mauvais commentaires, qui me conviennent parfaitement, sauf le cas des mauvais commentaires de type "commentaires de journalisation". Ce sont les commentaires que l'on ajoute en début de fichier ou de méthode pour indiquer pour quelle raison on y touche (identifiant de user story au minimum), la date, l'auteur. A supprimer absolument pour Robert C. Martin, étant donné que nos systèmes de gestion de source fournissent maintenant facilement cette information. Je suis d'accord sur le principe, mais pas sur la pratique !

En effet nous travaillons dans un cadre réglementaire et nous pouvons être audités par des clients, lesquels arrivent avec des formulaires d'évaluation du code qui exigent d'examiner... les commentaires ! J'ai constaté que les auditeurs n'étaient pas trop exigeants sur le détail des commentaires eux-mêmes, mais ils sont intransigeants sur le fait qu'il doit y avoir des commentaires. Donc à l'heure actuelle je ne suis pas confiant de présenter à des auditeurs du code très peu commenté (mais très lisible) comme le recommande Robert C. Martin. J'aurais un peu l'impression d'aller tout nu à l'audit...

Donc pour moi les commentaires de journalisation ont la fonction d'habiller un peu le code (et celui qui est audité). De plus les informations qu'ils contiennent sont assez utiles, notamment lors du support technique. Quand je travaille sur la résolution d'un bug mystérieux, et que j'arrive sur une certaine méthode, les commentaires de journalisation me sont utiles :

• une longue liste de commentaires m'indique que la mise au point a été laborieuse, et que je dois me méfier avant de modifier la fonction,
• un unique commentaire ancien m'indique une portion de code stable depuis longtemps. Est-il vraiment justifié d'y toucher maintenant ?
• les identifiants de user stories me renseignent les impacts possibles si je touche à cette méthode
• les noms de ceux qui ont travaillé successivement sur la méthode me renseignent aussi sur d'éventuels risques, ou sur des anti-patterns possibles.

Il est vrai que qu'un système de gestion de version de sources moderne peut fournir ces informations. Nous utilisons maintenant SubVersion qui offre la fonctionnalité "Blame", laquelle permet de voir "à plat" toutes les modifications d'un fichier. Il reste à voir si cette fonctionnalité est suffisamment performante (dans notre ancien système, certains fichiers ont été modifiés plus de 400 fois - est-ce que Blame fonctionne dans de tels cas ?).

Si Blame fonctionne réellement à cette échelle, je suis assez disposé à abandonner les commentaires de journalisation dans de futurs projets, à condition que le code soit développé suivant les principes exposés dans Clean Code.

Donc d'accord pour la nudité, mais à condition qu'elle soit magnifique !

Et vous, que pensez-vous des commentaires ? Que faites-vous en pratique ?

Remarque : vous pouvez lire un chapitre du livre en ligne ici sur informit.Com, c'est une introduction avec des interviews de programmeurs expérimentés (Bjarne Stroustrup, Grady Booch, Dave Thomas, et Ward Cunningham) qui expliquent ce que Clean Code veut dire pour eux.