Commenter ou ne pas commenter son code, telle est la question
Une des premières choses enseignées lors des cursus en développement informatique est la pratique de commenter proprement son code. Qu’il s’agisse des classes, des méthodes ou des variables, au sein du code applicatif comme des tests ou des fichiers de configuration, les annotations sont censées apporter du contexte et améliorer la compréhension et donc la maintenabilité du code. Pour autant, le débat sur leur utilisation n’est pas tranché. Un peu comme pour l’emploi des termes pain au chocolat ou chocolatine, plusieurs écoles existent. Et si cette question des commentaires est en apparence encore moins critique que celle sur les viennoiseries, elle recouvre en fait plusieurs aspects importants de la pratique de développeur.
Alors, commenter ou ne pas commenter ?
Les avantages de bien commenter
Fournir des annotations à son code permet à la fois d’expliciter la façon dont il s’exécute, de fournir un contexte important, de préciser des points clés et peut enfin servir de documentation. Elles permettent de souligner les éléments d’intérêt, par exemple en spécifiant la signature des méthodes : quels sont ses paramètres et qu’est-ce que celle-ci retourne ?
Donner du contexte aux variables ou aux constantes via des commentaires permet également de mieux comprendre à quoi elles servent et dans quel cadre elles sont pertinentes.
Dans l’exemple ci-dessous, nous avons spécifié à la fois en en-tête la signature de la méthode getNomViennoiserie mais aussi dans la méthode en fournissant un élément de contexte permettant de faciliter la compréhension :
De plus, commenter certains passages en lien avec certaines règles de gestion peut apporter une précision intéressante, voire nécessaire à la compréhension générale du code. C’est souvent utile lorsqu’appliqué sur du code métier complexe et de manière générale sur du code haut niveau.
Enfin, ajouter des commentaires peut aussi permettre de séparer le code en blocs cohérents comme on peut le voir au sein des tests avec les fameux Given (Etant donné que), When (Lorsque), Then (Alors). Mais cela peut aussi être utilisé de façon générale dans n’importe quelle fonction un peu longue et/ou complexe afin de la rendre plus claire et plus digeste.
Toutes ces astuces d‘annotation permettent en principe de gagner en lisibilité et donc en maintenabilité tout en fournissant une documentation précieuse. Sachant que disposer d’une documentation claire et à jour participe à répondre aux enjeux de maintenabilité d’un logiciel. Pour autant, les commentaires ne sont pas toujours utiles, voire peuvent même parfois s’avérer contre-productifs.
Commenter c'est douter...
Le code, c'est aussi de la documentation
Un des problèmes associés aux commentaires est qu’ils ajoutent des lignes au sein des fichiers de nos logiciels et applications, les rendant plus lourds au sens propre comme figuré. De plus, tout comme le code, les annotations doivent être mises à jour à chaque évolution. Par exemple si on doit faire évoluer une méthode qui renvoyait un booléen dont les conditions de retour ont changé. Le problème étant que, contrairement au code applicatif, il est facile d’oublier de modifier les commentaires puisqu’aucune erreur n’est déclenchée s’ils ne sont pas à jour.
On peut nuancer le point précédent car certains outils tels qu’Oxygen permettent de lever des erreurs si les commentaires ne correspondent pas à la signature de la méthode par exemple. Mais cela reste malgré tout quelque chose qu’on retrouve de manière assez fréquente : le code est bien mis à jour, mais la documentation ne l’est plus et peut même se retrouver à contredire le code qu’elle est censée documenter.
Allons un peu plus loin : le code sert de documentation, ne serait-ce qu’aux développeurs qui veulent par exemple vérifier l’implémentation de telle ou telle fonctionnalité. Le code, tant qu’il est suffisamment clair et bien structuré, est une source fiable car il correspond au fonctionnement de l’application ou du logiciel et ne peut donc pas mentir ou ne pas être à jour par rapport à l’existant : il est l’existant.
Bon ok, on enfonce un peu des portes ouvertes… Alors résumons ainsi : ajouter une documentation pour expliquer de la documentation, c’est peut-être simplement que la documentation d’origine (ici le code) n’est simplement pas suffisamment compréhensible pour se suffire à elle-même... On doit pouvoir lire le code presque comme lorsqu’on lit un livre, surtout lorsqu’il s’agit de langages évolués.
Rendre son code clair et maintenable
Un des critères de maintenabilité du code est qu’il soit clair, structuré et compréhensible. La plupart du temps, bien nommer les fonctions, les variables et constantes et simplifier son code en n’hésitant pas à factoriser le traitement réalisé en plusieurs fonctions suffit à le rendre intelligible et explicite.
Prenons un exemple de code java :
Ici, le commentaire dans la javadoc permet en effet de rapidement comprendre ce que fait la méthode getList. Mais le code n’est pas très propre, ne pourrait-on pas justement l’améliorer à tel point que le commentaire devienne obsolète ?
Déjà, prenons le nom de la méthode getList : il n’est pas très explicite, de quelle liste parle-t-on ? On pourrait commencer par la renommer en getListUtilisateursViennoiseriesFromFichier: On sait alors d’emblée qu’on parle d’une liste d’utilisateurs qu’on va récupérer d’un fichier et qui consomment des viennoiseries. Prenons ensuite le paramètre de la méthode, ici un id : si en renommant le nom de la fonction, on peut se douter qu’il s’agisse de l’id du fichier, c’est encore mieux de l’écrire explicitement : fichierId.
Allons encore plus loin, on filtre ensuite sur les lignes du fichier en fonction de plusieurs conditions : pourquoi ne pas simplement externaliser ces vérifications dans une méthode à part qu’on pourrait alors nommer ainsi : estValide. On peut faire de même en créant une méthode contientViennoiseries pour la ligne suivante. Enfin, nous pouvons également répéter le même genre d’opération pour le filtre appliqué sur les utilisateurs qui doivent posséder un nom et un prénom.
Voyons ce que tout cela donne en enlevant également les annotations :
A-t-on encore besoin des commentaires ? Certes, ceux-ci permettraient toujours d’expliquer ce que fait la méthode, mais cette dernière est maintenant beaucoup plus explicite. Il n’y a même pas besoin de maîtriser le code java pour comprendre ce qu’elle fait : son nom et le nom des variables et des autres fonctions appelées sont suffisamment clairs.
Les bonnes pratiques du dev en général
Finalement, au-delà du simple fait de commenter ou non son code, le sujet tourne davantage autour des bonnes pratiques de développement en général, à savoir :
- bien organiser et structurer son code ;
- bien découper les méthodes, ne pas hésiter à factoriser et à externaliser des blocs logiques ;
- bien nommer les méthodes et les variables afin que leurs intitulés soient explicites ; concrètement préciser ce que contient la variable (et non ce qu'elle fait) et préciser ce que fait et retourne la fonction (et non pas les paramètres)
De manière générale, on se rend compte que bon nombre de commentaires qu’on pouvait juger utiles deviennent en réalité obsolètes dès qu’on commence à appliquer ces bonnes pratiques.
Tu ne commenteras point !
Retournons maintenant la question initiale : devoir commenter son code n’est-il pas un aveu de faiblesse ; une solution de contournement pour expliquer ce qu’on n’a pas réussi à rendre intelligible autrement ? Pour le dire autrement, commenter n’est-il pas au fond douter sur le fait que le code qu’on a écrit puisse être facilement compréhensible ?
C’est souvent une pratique qu’on retrouve chez les débutants qui peuvent éprouver des difficultés à structurer leur code et à le rendre clair : rajouter des commentaires permet alors de compenser les lacunes. Mais il peut aussi y avoir des effets pervers à trop fournir d’annotations : savoir qu’il suffit d’ajouter quelques lignes de texte à son code pour « l’améliorer » peut indirectement inciter à faire moins d’effort pour rendre celui-ci clair en tant que tel.
On retrouve aussi parfois la tendance à répéter ce que fait le code en commentaire : typiquement ajouter une annotation // on récupère la liste sur une méthode getList(). Un tel commentaire n’apporte aucune plus-value et ne fait qu’encombrer les fichiers, il peut donc être supprimé.
Faut-il pour autant éliminer toute ligne de commentaire dans le code ?
Question de pratiques
Pain au chocolat ou chocolatine ?
Plutôt que de respecter une liste d’injonctions, écrire un code lisible et maintenable dépend du contexte de l’équipe et notamment de son niveau de maturité, de ses bonnes pratiques, des technologies utilisées, des obligations contractuelles demandées par les clients... Dans ce cadre, vouloir bannir toute annotation tout comme vouloir commenter chaque ligne ne sont pas des solutions. La vérité, si elle existe, est probablement quelque part entre les deux.
De manière générale, il s’agit plutôt d’évaluer la pertinence des commentaires :
- Pourrait-on s’en passer en réécrivant et en simplifiant le code ?
- Y a-t-il un risque de passer à côté de quelque chose ou de mécompréhension si on les retire ?
- Et donc finalement, apportent-ils une plus-value intéressante par rapport au code ? Le commentaire doit à la fois pouvoir permettre de confirmer le code tout en apportant une précision de compréhension, de contexte ou de documentation
Dans un certain nombre de cas, les commentaires apparaissent en fait comme indispensables :
- pour générer de la documentation sur les méthodes, exemples de la javadoc ou d’Oxygen.
- pour expliciter des points précis qui ne figurent pas dans le code sans trop alourdir les noms des méthodes ou variables, par exemple les unités lorsqu’il y en a (Cf exemple de code ci-dessous).
- pour préciser une règle de gestion complexe ou qui n’est peut-être pas intuitive.
- pour signifier qu’un bloc de code n’est pas terminé ou devra être enrichi (le fameux TODO qui reste pendant 5 ans…).
Pratiques communes
Enfin, il s’agit surtout de se mettre d’accord sur des pratiques communes partagées dans l’équipe, voire entre les équipes d’une même entité. Cela permet d’apporter un référentiel commun auquel se raccrocher et d’harmoniser les façons de faire. C’est un peu comme décider du nombre de barres de chocolat dans la recette de notre viennoiserie préférée... Cela permet aussi aux personnes de l’équipe de partager leurs points de vue sur ce sujet, d’échanger et de débattre en fonction des préférences, des habitudes et des points de vue de chacun. Enfin, cela peut également permettre de tester plusieurs façons de faire et de confronter les différentes solutions envisagées à la réalité avant de se mettre d’accord sur le choix des bonnes pratiques.
Conclusion
Alors, commenter ou ne pas commenter ?
À mon sens, il est presque toujours préférable de se passer des commentaires afin de se focaliser sur la lisibilité du code en tant que tel et, dans un second temps, d’ajouter des commentaires uniquement lorsqu’on le juge nécessaire. Mais si vous demandez à quelqu’un d’autre, cette personne pourrait vous dire qu’au contraire, commenter son code de manière systématique est une bonne pratique indispensable.
La réalité est qu’il s’agit probablement de ne pas prendre cette question des commentaires séparément, mais considérer les bonnes pratiques dans leur ensemble et les appliquer aux équipes en fonction du contexte. Finalement, peut-être faut-il moins penser ces bonnes pratiques comme une liste de choses à mettre en place, mais plutôt comme un tout cohérent, adapté et évolutif.
Et vous, vous êtes plutôt pain au chocolat ou chocolatine ?
Sources :
https://buzut.net/bien-commenter-son-code/