Les commentaires de code

Introduction

Demander aux développeurs de commenter leur code peut s'avérer être une tâche difficile et devenir un sujet qui fâche. Par manque de temps, sous la pression et le stress, les développeurs préfèrent parfois ignorer cette recommandation.

Comme les spécifications fonctionnelles et techniques, les commentaires de code sont tout aussi importants que le code, et doivent être pris en compte dans le temps de développement.

Dans un projet, il faut instaurer des règles et des normes afin qu'il ne parte pas dans toutes les sens. Des normes de développement existent pour cela, et les commentaires de code ne sont pas exclus.

Définition : commentaire

En informatique, le commentaire de code est un texte libre qui n'a aucun impacte sur le code, et est ignoré lors de l'interprétation et/ou la compilation car il n'est pas utile à l'exécution du code.

Le commentaire n'est qu'informatif pour favoriser une meilleure compréhension d'un ensemble ou d'une partie de code lors des phases de maintenance et d'évolution de l'application. Ces informations sont essentielles pour le développeur, c'est ce qui lui permet de rentrer rapidement dans le vif du sujet sans pour autant comprendre toute la technicité des instructions, rien qu'en lisant les commentaires ou les notes.

Utilité d'un commentaire

En l'absence ou non de documentations techniques et fonctionnelles, documents externes au code source, le commentaire de code devrait être le minimum syndical dans un projet informatique. Si le code est bien commenté, le commentaire peut être associé à une documentation détaillée interne au code source. Nous retrouverons ainsi la description du composant, sa fonction, son auteur, sa version, et toute autre information détaillant chaque étape du processus et des étapes pouvant être utile aux développeurs.

Commentez votre code ! On ne vous le répétera jamais assez. Un commentaire n'est pas une perte de temps, même si vous êtes le(la) seul(e) à développer votre application dans votre coin. Il est votre meilleur ami lorsque vous passerez en maintenance ou ferez une évolution. Son objectif est de vous faire gagner du temps dans la recherche de la partie de code à modifier, et dans la compréhension rapide du code.
Le commentaire explique ce que fait le code, indique s'il y a des contraintes, des conditions, des cas particuliers ou spécifiques, etc. Le commentaire est littéraire, ce que le code est technique.

Le commentaire est utile si :

il décrit l'action d'un bloc de code, simple ou complexe : si un jour, vous devez y apporter une modification, il vous sera plus facile et plus rapide de déterminer l'endroit à mettre à jour dans le fichier source en vous aidant des commentaires qu'en lisant et en essayant de comprendre directement le code ;
il est bien rédigé grammaticalement et est compris de tous : un autre développeur doit pouvoir comprendre aisément ce que fait le traitement. Dans le cas contraire, le commentaire ne sert à rien ;
il est le reflet de l'algorithme pensé durant les phases d'analyse et de conception : si vous supprimer tout le code pour ne voir que les commentaires, ces derniers doivent décrire fidèlement chaque étape du traitement.

Le commentaire s'écrit avant le bloc de code. Il permet d'annoncer ce que vous aller faire et délimite le champ d'action du bloc de code en réponse de la pratique du YAGNI. Nous pouvons le considérer comme une mini-documentation fonctionnelle interne au fichier source.

Apprendre à bien commenter son code

A l'école ou en formation, on vous conseille fortement de commenter votre code. En entreprise, on vous l'impose (plus ou moins) pour faciliter la maintenance et le passage de connaissance. Cela est bien beau, mais vous a-t-on dit comment commenter et comment bien le faire ?

Dans le monde de la programmation orienté objet, les normes de développement sont de rigueur pour bien structurer le code avec des règles de nommage précis sur les classes, les méthodes, les variables, etc. Et les commentaires n'y échappent pas. S'il existe des variantes sur les normes et les nommages, quelque soit le langage utilisé dans un projet, elles suivent toutes le même objectif : inviter les développeurs à adopter la même pensée, la même logique et le même style d'écriture afin que chacun puisse intervenir rapidement sur le code d'un autre, comme si c'était lui qui l'avait développé. La clé du succès pour un projet est l'unicité.

Pour savoir ce que vous devez commenter, la façon dont vous aller le faire et ce que vous devez y mettre, reportez-vous aux normes de développement de votre projet. Si elles n'existent pas encore, il faut les définir dès que possible, ou adopter celles déjà existantes proposées généralement par l'organisme/entreprise initiatrice du langage, pour que tous les développeurs puissent démarrer sur de bonnes bases.

Quelques cas réels en entreprise

Voici des remarques faites souvent en entreprise :

C'est quoi cette classe ?: Un nouveau développeur découvre une classe dont le nom est ésotérique et n'ayant aucune description de ce qu'elle est et sur ce qu'elle fait. Le nom de la classe ne lui parle pas, ou est trop générique pour savoir la façon dont elle peut être utilisée.

Je n'y comprends rien, c'est quoi ce code !: Soit il n'y a pas de commentaire, soit le commentaire a été rédigé par un extraterrestre nouveau né essayant d'apprendre le langage humain. Vous conviendrez que si le commentaire est incompréhensible, comment voulez-vous que le code soit autrement ?

Il faut mettre à jour les commentaires !: Le développeur a bien commenté au moment d'écrire son code. Mais au bout de quelques mois, plusieurs mises à jour ont été apportées et le traitement a évolué. Au final, le code ne correspond plus au commentaire initial, et fausse l'idée du comportement du bloc de code.

Tiens, je suis sûr que xxx est passé par là: Cela peut être un compliment... ou pas. S'il n'y a pas de normes de développement bien définit, chaque développeur peut développer comme bon lui semble. On appréciera un code propre et bien documenté, comme on pestera sur un code mal écrit ou avare en commentaire.

Je n'ai pas envie de passer derrière xxx: C'est ce que l'on appelle un travail bâclé. Certainement pris par le temps et le stress, le développeur n'a pas soigné son code, et encore moins décrit le fonctionnement de son code. La lecture est difficile et exige plus de concentration de la part du développeur qui reprend le code.

Toujours pas envie de commenter son code ?

Repousser le commentaire à plus tard, c'est ne jamais le faire, généralement par manque de temps, mais aussi parce-que c'est une tâche peu motivante pour un développeur à ne faire que ça. Et cela se comprend... Afin d'éviter cette phase fastidieuse, prenez l'habitude de commenter avant de développer votre bloc de code. Ensuite, traduisez votre commentaire en instructions. Par cette pratique, vous n'aurez pas l'impression de faire que du code, puis que du commentaire. De plus, lorsque vous reviendrez sur votre code 6 mois après, vous serez content(e) de retrouver vos commentaires, surtout si le code présente des tas d'astuces et de conditions particulières que vous avez oubliées.

Si tout cela vous semble inutile, et que vous ne souhaitez pas le faire pour vous, faîtes-le au moins pour les autres, par respect pour les membres de l'équipe et les futurs développeurs qui vont reprendre votre travail. Ces derniers ne sont pas dans votre tête, et ne peuvent pas deviner ce que vous avez voulu faire. S'ils ne sont pas aussi talentueux que vous, ou n'ont pas votre génie, ils risquent de saboter votre code involontairement par manque d'information et de compréhension.
En entreprise, il faut être réactif, et toute information aide à comprendre un code dont on n'est pas l'auteur, surtout pour éviter une régression.

On entendra souvent dire qu'un code propre et bien pensé n'a pas besoin de commentaire. Il y a effectivement une part de vérité, mais il faut bien comprendre que dans une équipe, tout le monde n'a pas le même niveau technique et d'expertise. En équipe, on ne code pas pour soi, mais pour les autres. C'est la première règle que tout développeur qui se respecte doit connaître et appliquer.

Mettre des commentaires dans son code, c'est comme y graver son emprunte. Si chaque développeur a son propre style pour coder, il a aussi sa propre manière de rédiger un commentaire. On saura toujours celui qui ne commente jamais son code, mais on reconnaîtra aussi toujours celui qui apporte une valeur ajoutée au projet.