Accueil > Réflexions > L’art de documenter

L’art de documenter

samedi 21 avril 2007, par Nicolas

J’ai eu plusieurs discussions avec des collègues sur comment, pourquoi, à quelle fréquence commenter ou documenter du code. Et ceci fait l’objet de nombreux débats sur Internet.

Pourquoi commenter [1] ? Simplement pour pouvoir, dans le futur, savoir ce que fait du code, et pourquoi et/ou comment il le fait. Ce besoin de savoir peut être lié à une recherche de bug, ou simplement de curiosité. De plus, le développeur ayant besoin de savoir n’est pas forcément l’auteur du code en question — mais même ce dernier bénéficie du commentaire quand il relit du code plusieurs mois après son écriture en ayant codé sur d’autres projets entre-temps.

Cependant savoir où, quand et comment commenter est très difficile [2].

La première règle est de donner des noms significatifs aux fonctions et variables, afin d’identifier leur signification. Ainsi void ResetMap(mapstruct* map) est plus parlant que void Reset(mapstruct* var) s’il s’agit d’une carte.

Un exemple de mauvais commentaire est du style :

   x = 0; /* initialisation */

ou

   /* Retourne le solde /*
   int GetSolde()
   {
   return solde;
   }

qui n’apporte strictement rien. Il arrive aussi que les commentaires soient totalement faux par rapport au code, donc leur signification devient nulle.

Il m’est arrivé de travailler dans des groupes où il fallait impérativement commenter toutes les méthodes, fonctions, classes publiques pour pouvoir archiver des modifications dans le contrôle de sources. Le problème est que de nombreuses propriétés ou fonctions n’ont tout simplement pas matière à commentaire — leur nom étant descriptif, bien entendu. Bilan, nous avons utilisé un programme pour extraire automatiquement les signatures (entrées, sorties) de ces éléments, et répondre à l’impératif de commentaires. À mon sens c’est une valeur ajoutée nulle, voire négative, car plusieurs fois je perdais du temps à rajouter les commentaires qui n’apportaient rien. Il aurait fallu faire en sorte qu’un archivage commente automatiquement en extrayant les informations, et laisser au développeur la responsabilité de savoir où le commentaire était nécessaire.

Pour moi, un commentaire doit répondre à différents critères pour être utile :
- ne pas paraphraser le code, ne pas dire comment on fait quelque chose, sauf si c’est vraiment très complexe — auquel cas il faut aussi se poser la question de simplifier ça. Lire le code répond en effet à la question du « comment », mais pas du « pourquoi ».
- dire pourquoi on fait quelque chose — « le chemin peut comporter des /, qui sont invalides dans un nom de fichier et doivent donc être transformés en _ »
- préciser quelle partie des spécifications fonctionnelles la fonction implémente — « cette fonction traite le cas spécifique de la réduction d’impôt de la loi xxx dans le cadre yyy », si le nom de la fonction ne suffit pas à indiquer cela
- indiquer les cas d’erreur de la fonction, ou ses présuppositions — « la carte peut être nulle, auquel cas la fonction ne fait rien », ou « l’objet doit être correctement initialisé par un appel à InitObject() avant d’utiliser cette fonction »
- éventuellement dire pourquoi une méthode a été choisie plutôt qu’une autre — « il est également possible d’utiliser tel algorithme, cependant il est plus compliqué à mettre en œuvre et n’apporterait aucun gain de performance sur de si petits ensembles de données »
- en règle générale, ne rien dire qu’un outil automatisé, comme Doxygen, ne puisse extraire


[1je vais utiliser ce verbe pour désigner le fait de commenter ou documenter, pour simplifier l’écriture.

[2je ne prétends aucunement être expert en ce domaine, d’ailleurs.