Comment or not comment ?

Je ressort d'une discussion avec des collègues concernant la pertinence des commentaires dans le code. C'est une question très terre a terre pour le développeur et si elle fait couler beaucoup d'encre, il en ressort souvent que finalement chacun reste sur son opinion malgré les recommandations et des remarques de bon sens.

En fait, c'est compréhensible, étant donnée que l'apprentissage de l'utilisation des commentaires fait partie ou presque des premières choses que l'on voit, il est normal que les premiers réflexes acquis soient les plus profondément inscrits.

Ainsi l’écriture des commentaires est presque culturelle et souvent les arguments allant en faveur de leur utilisation vont citer par exemple la nécessité de réaliser un code maintenable, de fournir une description plus fine des tests, de préciser les points susceptibles d'évoluer ou même d’être corrigés. Ainsi pour beaucoup, l'utilisation des commentaires dans le code a son importance et un code non commenté n'est pas un bon code.

Mais... autant le dire tout de suite, je ne suis pas de cet avis et avant de crier au scandale, de retourner la table et d'arracher les rideaux, laissez moi exposer mon point de vue.

Je vais commencer par préciser que je parle ici de commentaires dans le code source, pas de la pertinence de la documentation technique. Je ne considère pas non plus que la javadoc s'assimile a du commentaire même si la frontière est mince est que certaines critiques identiques a la production de commentaire pourrait également être faites.

Alors voila, je suis un grand fan de la POO, et en ce sens, je considére qu'un code bien écrit est

• simple (on écrit que des choses évidentes), 
• explicite (on nomme les chose par leur nom), 

et qu'il

• respecte la règle des 7+/-2 de Miller (qui si elle n'est qu'une règle a suivre ne doit pas devenir une contrainte) donc on va avoir  7+/-2 lignes par méthodes, 7+/-2 méthodes par classe, 7+/-2 classes par package, 7+/-2 package par sous-package, etc.... 
• limite les structures lourdes (par exemple, en java, on évitera l'utilisation, des switch/case, on préférera le polymorphisme a la cascade de if/then, etc)
• fournit une documentation technique (ou dossier d'architecture) efficace.

(Alors bien sur pour les fan des approches fonctionnelles, ça vaut aussi bien sur mais adapté forcement au langage employé)

Donc a mon sens un code bien écrit respecte par lui-même un standard de lecture facile. Qui fait que si un commentaire "utile" doit être écrit c'est que probablement le code peut être simplifier ou revu afin de tendre vers un code explicitement évident. Je précise "utile" car malheureusement et souvent un code commenté n'est commenté que par des paraphrases inutile qui au contraire vont en alourdir la charge textuelle.

D'autre part il ne faut pas oublier qu'un langage de programmation est fait nous. En fait il ne s'agit que d'une interface homme machine dédié au développeur.... techniquement, notre ordi s'en moque que l'on écrive en C++, en Java, en SmallTalk ou en Scala... Dans l’idéal il veut de l'assembleur voir des 0 et des 1 (pour caricaturer....) Donc le langage a été élaborer afin de nous permettre un certain degré d'expressivité selon un certain nombre de concepts. Il ne faut pas non plus oublier qu'un langage est formelle dans sa définition et permet de décrire des comportements prédictibles ce que ne permet pas le langage naturel (qui de plus ne sera accessible qu'a ceux parlant votre langue....) Apres tout, lorsqu'il effectue une compilation, la première chose faites par le compilateur, c'est de supprimer les commentaires....

Certains vont continuer a défendre que malgré tout il existe des algorithmes qu'il est nécessaire de commenter. A mon sens, effectivement, l’emploie des commentaires peut n'avoir vraiment de sens que pour une chose: la description d'algorithmes optimisés et spécifiques.  Dans ce cas de figure on est en présence d'informations ne pouvant pas forcement faire partie d'un dossier de conception car relevant de détails d’implémentation trop précis. Alors bien sur, même ça, est discutable, et on pourra faire un billet également sur ce que doit contenir un dossier de conception.... mais c'est un autre problème. Il faut être pragmatique et savoir reconnaître que ces détails d'optimisation de la complexité et de performances ne peuvent tous être défini par l'architecture.

Cependant lorsque l'on considère ce besoin on oublie le contexte environnemental du développement logiciel. En effet, le développement logiciel actuel nécessite l'emploi d'un gestionnaire de source tel que Git, Subversion ou Mercurial. Ces outils sont indéniablement une avancée majeure dans le développement, l’intégration continu, ou la gestion de versions. Cependant, ils ont un bais lié a leur emploi, c'est qu'ils gèrent tous incrementalement les sources logicielles. Ça parait évident car c'est leur but, mais en fait dans la gestion des commentaires, ça pose un vrai problème. En effet contrairement au code qui est, si de bonnes pratiques sont appliquées, compilé testé avant d’être intégré dans une branche principale, les commentaires ne le sont pas. 

On va me répondre : "ba oui c'est normal, c'est pas le commentaire que l'on exécute! "

Oui effectivement, donc je vous poserai alors la question: qu'est ce qui vous permet de garantir que ce que le commentaire décrit correspond à la version du code présenté? Et bien rien; et a part faire de l’archéologie dans votre gestionnaire de sources pour garantir que à chaque modification du code, une modification du commentaire a été réalisée... et bien vous ne pouvez pas sauf en ayant foi en vos prédécesseurs.... tous....

Du coup.... vaut il mieux devoir comprendre un bout de code un peu trop complexe ou vaut il mieux chercher a savoir si un commentaire est fiable pour nous aider a comprendre ce code qu'il faudra finalement appréhender pour le modifier? Moi je pense que oui... car finalement les commentaires c'est pas fiable et ca ne pousse pas a écrire un code propre....

Mais alors faut il commenter son code? Et bien, pour dernier argument, pensez au temps que vous allez passer a écrire et maintenir ces commentaires en plus du code source et du coup que çà aura pour chacun de devoir le subir... et la  Si vous restez persuader du bien fait des commentaires, et bien poursuivez votre lecture avec  Ardalis et un Hinault, peut être arriveront ils a vous convaincre.