Clean Code : partie 3 – les commentaires

Depuis un certain nombre d’années, le débat relatif à l’importance ou à l’inutilité des commentaires  au sein du code fait rage.

D’un côté, les partisans du tout commentaire, pensent que la présence de commentaires est indispensable à la compréhension du code, et que par conséquent, toute portion de code doit être commentée. Le fait de ne pas commenter suffisamment le code est perçu comme une forme de paresse.

De l’autre les paresseux adeptes du commentaire parcimonieux, considèrent les commentaires comme une forme de nuisance associée au code, une sorte de mal nécessaire qui doit être réservé aux situations pour lesquelles on ne peut faire autrement. J’ai tendance à privilégier cette seconde approche par flemme pragmatisme.

Les commentaires sont souvent faux

Le code, par sa nature exécutable, ne ment jamais, dans le sens où il fait ce qu’il dit (même si dans ne nombreux cas c’est mal dit et que ce n’est pas très clair). Pour apporter davantage de clarté, nous disposons des commentaires, qui ont vocation à expliquer ce que le code fait. Seulement, en ce qui concerne la véracité des explications, on est obligé de croire le développeur qui en est l’auteur sur parole, et dans la pratique il arrive fréquemment que le commentaire ne soit pas en accord avec la réalité du code.

Le problème tient, d’une part, du fait que chaque développeur va expliquer les choses comme il peut, avec plus ou moins de succès, et que d’autre part, rien n’oblige à maintenir les commentaires conjointement au code, notamment en cas de tensions dans le planning de livraison. Dès lors, les commentaires se trouvent fréquemment en décalage, voire en contradiction avec la réalité du code décrit.

Les commentaires sont souvent redondants

Il est fréquent de rencontrer des commentaires qui paraphrasent ce que le code (ou l’environnement associé au code) décrit déjà de façon évidente, en violation du principe DRY (Don’t Repeat Yourself). En voici quelques exemples :

Journal des modifications

Ces commentaires se trouvent généralement en en-tête de fichier et documentent la liste des changements, la date de survenue et l’auteur. Ces commentaires font bien évidemment double emploi avec le VCS (version control system), qui lorsqu’il est bien utilisé, comporte pour chaque commit un commentaire précis de ce qui a été fait (en plus d’indiquer la date et l’auteur automatiquement).

Certains IDE activent par défaut un template de génération de commentaire indiquant la date de création et l’auteur, il convient donc de les désactiver dans les paramètres afin d’éviter de polluer le code.

Description d’une variable ou d’une méthode

On rencontre parfois ce genre de commentaire :

String str; // for separator token

Alors que l’écriture suivante est tout aussi efficace, en plus de rappeler le rôle de la variable tout au long de son utilisation dans le code :

String separatorToken;

D’une manière générale, lorsqu’un identificateur (de variable, de classe, de méthode, d’attribut, de paramètre) est décrit par un commentaire, il faut se demander si un renommage ne serait pas suffisant pour porter cette intention.

Description des traitements

Certains commentaires vont délimiter les différentes phases d’un traitement ou d’un algorithme, notamment au sein d’une méthode. Si cette documentation est vraiment nécessaire, cela peut être révélateur que la méthode en question fait trop de choses (en violation du Single Responsibility Principle) et qu’un refactoring devient nécessaire. En combinant un découpage approprié et des renommages explicites, on parvient dans la plupart des situations à se débarrasser de ces commentaires superflus.

Documentation d’API / Javadoc

En tant que convention, toute méthode à visibilité publique en Java devrait s’accompagner de commentaires sous forme de Javadoc, qui décrivent le rôle de la méthode, de ses paramètres, des valeurs retournées et des exceptions susceptibles d’être levées. Seulement, le surcroit de travail induit par cette convention est-il pertinent ?

Dans de nombreux cas, quand on se penche sur une Javadoc, on se rend compte que, ou bien les commentaires ont été générés par l’IDE, ou bien la description saisie manuellement paraphrase le code. Dans ces deux cas, la Javadoc n’apporte rien à l’utilisateur.

Les Javadoc les plus utiles, telles que celles qui accompagnent les classes du JDK, nécessitent un investissement important de la part de leur développeur. Le respect de leur cohérence avec le code est surveillé scrupuleusement.

Dans mon expérience, les cas de Javadoc les plus utiles sont ceux qui sont assortis d’exemples d’utilisation du code. Il existe toutefois une alternative plus intéressante consistant à fournir ces exemples sous forme de tests unitaires. Cela offre le double avantage d’assurer en permanence une adéquation avec le code, tout en améliorant la qualité par leur nature de tests.

Code mort

Cette utilisation récurrente des commentaires permet de désactiver facilement du code, tout en offrant la possibilité de le réactiver facilement à l’avenir. L’expérience montre que le code en question est rarement réactivé. Nettement plus grave, le code en question est rarement nettoyé, polluant le code pour les années et les générations de développeurs à venir, qui la plupart du temps n’oseront pas supprimer ce code commenté (en se disant qu’on ne sait jamais, ça pourrait servir).

En réalité, un tel code peut être supprimé sans regrets. Il n’est jamais totalement perdu, puisqu’on pourra le retrouver dans l’historique du VCS. Mais le meilleur réflexe consiste à ne jamais committer de code commenté. Si le code est dans une phase de transition, on pourra utiliser des techniques plus efficaces telles que le feature flipping.

Les commentaires, c’est vraiment mal ?

De tout ce qui vient d’être dépeint, on pourrait penser que les commentaires devraient être proscrits, voire que la possibilité soit supprimée des langages de programmation. Ce n’est pas vraiment le cas, néanmoins il est nécessaire de garder à l’esprit que la présence ou la supposée nécessité des commentaires devraient être des indices sur une possibilité de mieux écrire le code. En effet, dans la plupart des cas, une écriture plus judicieuse du code rend les commentaires inappropriés.

Toutefois, il existe des cas pour lesquels on a peu de choix. Notamment pour expliquer des effets de bords, des contournements ou encore des subtilités d’ordre métier (ou techniques, liées à des spécificités d’API par exemple). Dans ces cas, il est préférable d’avoir des commentaires plutôt que pas d’explications du tout. Quand il y a dilemme, c’est la préoccupation liée à la clarté du code qui devrait primer.

Enfin les commentaires sont tout à fait adaptés, lorsqu’il s’agit de baliser des améliorations ou des corrections à faire dans le futur (les fameux //TODO ou //FIXME).

Laisser un commentaire