Votre code a-t-il vraiment besoin de commentaires ?

Les développeurs passent souvent plus de temps à lire du code qu’à en écrire. Réduire ce temps de lecture, c’est gagner en productivité : plus de temps pour innover, moins à déchiffrer l’héritage d’un collègue.

Cela commence par un code lisible, clair et sans ambiguïté. Mais qu’en est-il des commentaires ? Le code décrit ce que le programme fait, rarement pourquoi il le fait. C’est là que les commentaires trouvent leur vraie valeur.

Les bons commentaires

• Ceux qui expliquent pourquoi ce code existe, pas ce qu’il fait.
• Ceux qui clarifient des parties complexes, comme une expression régulière.
• Ceux qui signalent l’importance critique d’une ligne ou d’un bloc.
• Ceux d’un développeur expérimenté qui guide les juniors dans du code délicat.
• Ceux liés à des obligations légales.

Les commentaires à éviter

• Les noms et dates de modifications : c’est le rôle du gestionnaire de versions.
• Les cadres décoratifs et rangées d’étoiles inutiles.
• Les TODO laissés dans le code au lieu d’un outil de suivi.
• Les commentaires excessifs sur du code déjà limpide.
• Les commentaires obsolètes, jamais mis à jour.
• Le code laissé en commentaire, source de confusion.

En résumé, les commentaires restent utiles, mais doivent être utilisés avec discernement pour réellement aider à la compréhension et à la maintenance. Et à ceux qui pensent que « le code ne ment jamais », je réponds en souriant : c’est vrai… à condition d’être dans la bonne branche.