Par conséquent les participants des dojos sont tous d’accord sur le fait qu’il faut bien nommer les tests. Rien de très surprenant, me direz-vous, c’est une bonne pratique bien connue. Par exemple dans Clean Code, le livre de l’oncle Bob dont j’ai parlé dans un billet précédent, il y a plusieurs points qui parlent du nommage correct. Le deuxième chapitre, écrit par Tim Ottinger, est même entièrement consacré à la question du nommage. Plus loin dans le livre, le chapitre « Tests propres » mentionne notamment :

Qu’est-ce qui rend un test propre ? Trois choses. Lisibilité, lisibilité et lisibilité. La lisibilité est même peut-être plus importante dans les tests unitaires que dans le code de production. Qu’est-ce qui rend les tests lisibles ? La même chose qui rend tout code lisible : clarté, simplicité et densité d’expression. Dans un test vous voulez dire beaucoup avec aussi peu d’expressions que possible. […]

La lisibilité du nom du test est donc importante pour avoir un test « propre ». Enfin dans le chapitre « Odeurs et heuristiques », il y a plusieurs points sur les noms, comme :

N1 : choisissez des noms descriptifs

N’allez pas trop vite pour choisir un nom. Assurez-vous que le nom est descriptif. Rappelez-vous que les significations tendent à dériver au fur et à mesure que le logiciel évolue, donc ré-évaluez fréquemment les noms que vous choisissez.

Ce n’est pas simplement une recommandation pour faire joli. Dans le logiciel les noms constituent 90% de ce qui rend le code lisible. Vous devez prendre le temps de les choisir soigneusement and de les garder pertinents. Les noms sont trop importants pour être traités à la légère.

[…]

N4 : des noms non-ambigus

Choisissez des noms qui rendent non-ambigus le fonctionnement d’une fonction ou d’une variable. […]

Pour l’instant je n’ai pas prêté suffisamment attention à cette question des noms des tests. J’utilisais le premier nom qui me venait à l’esprit. Suite à la « découverte » de cette bonne pratique grâce aux dojos, j’ai donc revisité mon tutoriel sur le développement dirigé par les tests (TDD), et essayé d’améliorer les noms des tests. Le tableau ci-dessous présente les noms de tests du tutoriel, ainsi que le nouveau nom que je leur ai trouvé, parfois avec difficulté.

Pour ce tableau j’ai suivi la convention utilisée par mes collègues, à savoir des groupes de mots séparés par des caractères « souligné », comme dans LeNombreDeSolutionsCalculees_DoitEtreEgal_AuNombreDeSolutionsTheoriques. Mes collègues ne trouvent pas très lisibles d’autres conventions comme tout séparer par des « souligné », comme dans le_nombre_de_solution_calculees_doit_etre_egal_au_nombre_de_solution_theoriques, ou comme tout regrouper et « séparer » par des majuscules, comme dans LeNombreDeSolutionsCalculeesDoitEtreEgalAuNombreDeSolutionsTheoriques.

En ce qui me concerne j’ai une préférence pour le_nombre_de_solution_calculees_doit_etre_egal_au_nombre_de_solution_theoriques, tout simplement parce qu’il est facile d’automatiser l’obtention d’un tel nom : il suffit d’écrire une phrase en français, et une simple macro permet d’obtenir un nom satisfaisant pour un compilateur (voir par exemple Macro to aid BDD test naming style). La troisième convention est également automatisable, mais moins lisible à mon goût.

Pour mieux comprendre les noms ci-dessous, il faut savoir que les 12 pentaminos sont représentés chacun par une lettre qui correspond à sa forme : X, L, V, I etc.

Obtenir de bons noms a été finalement assez difficile, et consommateur de temps. D’ailleurs je ne suis pas forcément satisfait de tous. Il est probable que travailler en binôme sur la question permettrait d’arriver à de meilleurs résultats.

J’ai constaté aussi que la difficulté de trouver certains noms pouvait indiquer une « mauvaise odeur ». Par exemple pour ApresAjoutDeV_EnPosition1_LesLibertesDePlace_DoiventEtreJustes_EnDiversEndroits, la longueur et le caractère vague  du nom m’indiquent que le test fait sans doute trop de choses, et qu’il vaudrait mieux le couper en plusieurs petits tests.

Travailler sur les noms a été également révélateur de défauts potentiels de structuration de mes tests. Ainsi l’une des classes comporte quatre méthodes dont les noms sont construits de manière similaire : PourUnPlateauVide_LePentaminoP_PeutEtreAjoute_EnPosition62, PourUnPlateauVide_LaProchainePositionLibre_DoitEtre1, PourUnPlateauVide_LaPosition1_DoitEtreLibre, PourUnPlateauVide_AucuneSolution_NeDoitEtreTrouvee, alors que les autres noms sont bien différents. Cela indique que ces quatre méthodes devraient certainement aller sur une autre classe de tests, ce qui permettrait de factoriser le contexte « Pour un plateau vide ». Les noms pourraient alors être simplifiés, ce qui augmenterait la lisibilité.

En conclusion, appliquer cette bonne pratique a été un exercice utile pour améliorer mon tutoriel dans une future version, et c’est une pratique que je m’efforcerai d’appliquer au quotidien.

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 :

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.