Est-ce une bonne pratique de commenter son code ?
Pourquoi la plupart des commentaires sont à éviter, et lesquels sont à garder
“Et surtout, n’oublie pas de bien commenter ton code !”
Combien de fois avons-nous pu entendre cette remarque lors de nos études ?
Le code se doit d’être le plus compréhensible possible afin que d’autres développeurs puissent le comprendre facilement, quoi de mieux dans ce cas là que de commenter en détails tout ce que fait le code ?
Faux ! Et archi faux !
Commenter son code est une mauvaise pratique, du moins, le commenter comme suggéré ci-dessus.
Quels commentaires sont à éviter absolument ?
Les commentaires qui expliquent l’intention du code
Ce genre de commentaire vient pallier un code dont l’intention n’est pas claire :
Pourquoi c’est un problème ? Car le code et le commentaire peuvent diverger. Si le tableau doit finalement contenir uniquement les jours ouvrés d’une semaine, et que le développeur ayant fait la modification oubli de mettre à jour le commentaire, alors celui-ci véhicule maintenant une information erronée, devenant contre-productif.
L’exemple est très réduit ici, mais il faut imaginer que ce genre de commentaire pullule dans le code, et pas uniquement pour décrire une variable :
Sans les commentaires, on aurait beaucoup de mal à comprendre ce que fait le code. On peut alors être tenté de se dire que les commentaires sont ici pertinents, car ils explicitent l’intention du code. Mais il existe déjà une façon d’expliciter son code, et c’est tout simplement avec du code !
À chaque fois que vous êtes tentés d’écrire un commentaire qui explicite l’intention du code, il est préférable de s’interroger : “Pourquoi me sens-je obligé d’ajouter un commentaire ici ? Qu’est-ce que je pourrais faire pour ne pas avoir à l’écrire ?”
La réponse est simple : mieux nommer ses variables et encapsuler le code dans des fonctions bien nommées :
Les commentaires redondants
Certains commentaires n’apportent rien de plus que ce que dit déjà le code. Les développeurs débutants ont tendance à écrire beaucoup de commentaires de ce genre, pensant bien faire. Voyons un exemple très simple :
Ici le commentaire est superflu et doit être supprimé pour ne pas polluer le code.
Le code commenté
Et oui, le code commenté (c’est-à-dire des lignes entières de code que l’on a commentées pour qu'elles ne s'exécutent pas) est aussi une forme de commentaire ! Généralement, nous sommes tentés de commenter un bout de code quand nous estimons que nous n’en avons plus besoin, mais sait-on jamais : “dans le doute mieux vaut juste le commenter plutôt que le supprimer”.
Finalement, la codebase se retrouve remplie de code commenté, ce qui la pollue considérablement.
Un code qui est commenté doit donc être supprimé.
Les commentaires trop longs
Certains commentaires sont beaucoup trop longs, véhiculant ainsi trop d’informations.
C’est notamment le cas des commentaires qui décrivent des algorithmes complexes, en détaillant chaque étape précisément.
Décrire les étapes d’un algorithme est très important, mais cela peut être fait par le code dans une certaine mesure.
Il est donc préférable dans ce cas de séparer les différentes étapes de l’algorithme en petites fonctions bien nommées, dont le nom indique clairement l’intention.
Si le commentaire donne des exemples de résultat de l’algorithme, il est préférable de faire figurer ces exemples dans des tests unitaires, qui resteront nécessairement en synchronisation avec le code, contrairement au commentaire.
Cependant, il peut être pertinent de garder un commentaire général expliquant le choix de cet algorithme par exemple, ou expliciter un détail important propre à l’environnement et au contexte.
La transition est donc toute trouvée pour parler maintenant des bons commentaires.
Quels commentaires écrire ?
Documenter une API publique
Les commentaires peuvent faire office de documentation. Beaucoup d’outils utilisent ces commentaires pour générer une documentation d’une API par exemple.
Ces commentaires ne “commentent” plus le code, mais le “documentent”. C’est radicalement différent.
La documentation est un outil de communication indispensable.
Préciser l’intention derrière un “hack”
Il arrive parfois d’avoir à écrire du code dont nous ne sommes pas très fier… Ce code peut paraître assez obscur.
Quand bien même il serait à l’intérieur d’une fonction bien nommée, le “pourquoi il/elle a fait comme ça ?” n’est pas clair, car c’est un “hack”, autrement dit une solution un peu “bricolée” mais qui fonctionne.
Dans ce cas-là il peut être intéressant d’expliquer pourquoi ce hack est nécessaire grâce à un petit commentaire.
Informer sur des choix liés à des notions métiers complexes
Si l’on reprend l’exemple de l’algorithme mentionné un peu plus haut, le choix de cet algorithme peut être une information intéressante à véhiculer aux futurs développeurs.
En effet, le choix précis de cet algorithme découle probablement d’une réflexion poussée qu’il est utile de partager, pour que les futurs développeurs comprennent le contexte dans lequel ils évoluent.
Il peut aussi être pertinent d’ajouter en commentaire un lien vers une documentation ou un document officiel si l’on a trait à des règles légales par exemple.
Pour résumer
Gardez en tête qu’un commentaire doit être synchronisé manuellement avec le code qu’il commente.
Un mauvais commentaire est donc un commentaire qui n’apporte aucune information supplémentaire par rapport à du code bien écrit, et qui en plus a la possibilité de diverger de celui-ci si, véhiculant ainsi de fausses informations.
Un bon commentaire a une valeur informative, que ce soit pour de la documentation (API publique par exemple) ou pour apporter un contexte supplémentaire qui ne peut être exprimé par le code (comme un lien vers un document officiel par exemple, auquel on peut se référer pour comprendre le contexte du code).
Happy Coding :)