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 :
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.
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.
Voici des remarques faites souvent en entreprise :
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.