Pourquoi il ne faut pas abuser des commentaires

Introduction

Les commentaires dans le code sont souvent vus comme une super bonne pratique pour aider à la compréhension.
Mais si tu es familier avec Clean Code de notre fameux Oncle Bob, tu sais qu’il adopte une position bien différente.

Dans ce livre culte, Oncle Bob nous propose une approche minimaliste des commentaires.
Il soutient que le meilleur code est celui qui se passe de commentaires.

Alors, pourquoi un expert comme lui va à l’encontre de ce que beaucoup considèrent comme une super bonne pratique ?
Regardons les raisons derrière cette approche radicale et réfléchissons à quand et comment les commentaires sont vraiment justifiés.

Le code doit être auto-explicatif :

La 1ère idée clé est que le code doit parler de lui-même.
Si tu as besoin d'un commentaire pour expliquer ce que fait ta fonction ou ta variable, c’est souvent un indicateur que le code lui-même n'est pas assez clair.
L'objectif est de nommer les variables et les fonctions de manière à ce que leur rôle soit immédiatement compréhensible.

// incrémente l'index de la boucle
i++

Ici, le commentaire ne donne aucune info utile. On a pas besoin d'explication supplémentaire pour comprendre ce que fait cette ligne de code.

Dans un code propre, des noms de variables comme : totalItems, incrementIndex ou isLoggedIn racontent déjà une histoire.
On comprends immédiatement l’intention derrière.

Les commentaires sont souvent périmés :

Un autre problème majeur soulevé par Oncle Bob est que les commentaires ne vieillissent pas très bien.
Lorsque le code évolue, il est fréquent d'oublier de mettre à jour les commentaires en conséquence.
Cela peut créer une situation où le commentaire ment, c'est-à-dire qu'il décrit un comportement du code qui n'existe pas ou plus.

C'est non seulement source de confusion, mais ça nuit également à la lisibilité globale.
Un dév qui se fie au commentaire pour comprendre une fonctionnalité sera induit en erreur.

Les commentaires inutiles polluent :

L’un des pires usages des commentaires, selon notre fameux Oncle, est leur utilisation pour redire ce que le code fait déjà clairement.
Des commentaires du type :

// ouvre le fichier
File file = new File("data.txt");
file.open();

Cela n'apporte aucune valeur ajoutée et, au contraire, ça rend même le code plus lourd à lire.
En surchargeant les fichiers avec des commentaires inutiles, on crée un environnement où l’essentiel du code devient plus difficile à repérer et comprendre.

Quand les commentaires sont vraiment utiles :

Cela dit, notre fameux Oncle ne prône pas la suppression complète des commentaires.
Il reconnaît que certains contextes nécessitent une explication plus détaillée.

Par exemple :

• Contextualiser une décision complexe : Si une approche particulière a été choisie pour résoudre un problème technique spécifique ou pour contourner une limitation, un commentaire peut être justifié pour expliquer cette décision.

• Références externes : Lorsqu’un code dépend d’un bug ou d’un comportement spécifique d’une API ou d’un système tiers, un commentaire peut fournir un contexte précieux pour comprendre pourquoi le code a été écrit de cette manière.

// Cette méthode utilise un workaround pour contourner le bug #1234 dans la bibliothèque externe XYZ

Par exemple, ce genre de commentaire est utile :-)

Ce type de commentaire aide nos futurs ex-collègues à comprendre des décisions non évidentes, sans avoir à faire de l'archéologie dans des tickets de support ou ailleurs.

Le code propre c'est mieux que des commentaires :

La conclusion principale de Clean Code est simple : plutôt que de commenter votre code, écrivez-le proprement dès le départ.
Les commentaires ne devraient jamais être une béquille pour compenser un code mal conçu.
Un code bien structuré, lisible et maintenable réduira naturellement le besoin d’explications supplémentaires.

Si un commentaire est nécessaire, c’est souvent un signal que quelque chose peut être amélioré dans la manière dont le code est rédigé.

Conclusion

Les commentaires dans le code, bien qu'utiles dans certains cas, ne sont pas une solution magique pour rendre le code plus compréhensible.
La clé réside dans la clarté et la simplicité du code lui-même.
Un code propre, bien structuré et auto-explicatif minimisera le besoin de commentaires et contribuera à une meilleure maintenabilité du projet à long terme.

Le message d'Oncle Bob est assez clair : codez proprement, commentez avec discernement.