La documentation sera toujours utile
Cet article est libre d'accès pour tous grâce à ceux qui soutiennent notre blog indépendant.
L’article "Les meilleurs commentaires ne s’écrivent pas" que j’ai publié il y a quelque temps déjà a fait couler pas mal d’encre sur les réseaux sociaux et les blogs.
Je suis content d’avoir fait réagir et d’avoir pu échanger sur le sujet avec plusieurs d’entre vous.
J’écris cet article en réponse à celui-ci : "Oui la documentation est utile" de Xavier Nayrac.
J’apprécie ceux qui prennent le temps, comme Xavier, d’écrire un article réponse qui permet peut-être de mieux exposer leur argumentaire constructif que dans un commentaire de blog ou sur les réseaux sociaux. Bien sûr, j’apprécie aussi que l’on m’envoie les liens de ces articles : quitte à répondre, autant que je puisse lire ces réponses.
La documentation est utile !
Je tiens à préciser que, selon moi, tous les commentaires font partie de la documentation, car ils participent tous à la bonne compréhension du code, des choix techniques et de ce fait, du projet en général. Après, qu’ils suivent une norme (JSDoc, PHPDoc, JavaDoc, etc) ou pas est un choix secondaire fait par l’équipe.
Donc oui, les commentaires ou la documentation sont très importants. Je n’ai jamais dit le contraire ! Je ne comprends pas comment certains ont pu penser cela en lisant mon article.
Le sujet n’est pas : est-ce qu’il faut arrêter d’écrire des commentaires ? Selon mon idée de base, ce serait plus : Priorisez les choses. Attachez-vous d’abord à écrire un code "parfait" avant d’écrire des commentaires. N’écrivez que des commentaires utiles pour les lecteurs/utilisateurs potentiels de votre code (dont vous-même dans un an).
Trop de commentaires étouffent le code
L’auteur se plaint ensuite que, dans un projet en cours:
"[…] la plupart des commentaires écrits sont des commentaires qui n’existent que pour passer les tests. Ils sont redondants & inutiles."
En voyant le code donné plus haut en exemple, on peut comprendre sa position. Je peux aisément comprendre. Mais la plainte ne me semble pas clairement formulée. Qui est responsable, selon l’auteur ? L’outil ? Des collègues qui ne jouent pas le jeu ? Le management qui impose un process trop strict ? Ça m’intéresserais beaucoup de connaître le sentiment de l’auteur à ce sujet, car j’ai l’impression que l’article blâme la documentation alors que le problème est ailleurs.
Pour répondre à la question de Xavier, ici je ne blâme ni le commentaire en lui-même, ni les collègues qui ne jouent pas le jeu (un peu quand même). Le réel problème selon moi est le code mandaté qui pousse le développeur à faire le minimum syndical pour passer à autre chose ou à laisser le commentaire autogénéré par son IDE.
Je montre une conséquence négative du commentaire mandaté pour expliquer pourquoi je ne suis pas entièrement pour.
Je ne critique pas la JSDoc ici. Je critique cet exemple de JSDoc médiocre. Je critique la qualité de ce commentaire.
"Dites moi qu’il y a une information dans ce commentaire que vous n’aviez pas en lisant le code !"
[...] Une première sur les types, ce qui est toujours bon à prendre avec un langage dynamique. Je vois que ça fonctionne avec une chaîne de caractère, et pas avec un objet File ou Path ou autre chose encore qui aurait du sens dans mon langage, dans mon framework, etc.
Le nom de la variable est filename, autrement dit "nom du fichier". Je vois difficilement comment mon paramètre "nom du fichier" peut être de type File ou "fichier".
Pour le type Path c’est effectivement plus probable, mais bien souvent on considère le nom du fichier comme étant une partie du path de ce fichier. Personnellement, si j’attends un path en entrée, j’appelle ma variable path.
Le choix des noms de variables est une partie importante du nettoyage et de l’amélioration du code.
[...] Et j’ai une seconde information sur l’importance relative de cette méthode : si elle mérite une telle documentation c’est sûrement qu’elle est destinée à être utilisée par d’autres objets appartenant à d’autres classes.
Sauf si comme je l’ai expliqué dans l’article, le code est mandaté. Dans ce cas, toutes les méthodes sont documentées. Toutes les méthodes sont donc importantes. Plus aucune ne l’est...
Surtout que même en l’état actuel de la fonction, cette documentation pourrait être largement améliorée.
Bien sûr qu’elle pourrait être améliorée ! C’est bien mon problème ! Là, les développeurs qui ne jouent pas le jeu sont à blâmer.
Encore une fois, mon article ne dit pas qu’il ne faut pas écrire de commentaires/documentations, mais que si l’on doit en écrire, elle doit être utile pour le lecteur.
Malheureusement, lorsque le développeur est obligé d’écrire de la documentation pour pouvoir commiter son code, il arrive des situations où il en écrit uniquement pour passer des tests et que son commit soit accepté. Lorsqu’il revient sur ce code plus tard, puisque les tests passent, il ne pense pas à modifier son commentaire pour le rendre plus utile.
La couverture par la documentation
Contre productif ? Permettre aux utilisateurs de votre code, ou à vous même dans 1 an, dans 3 ans, de comprendre le code en un claquement de doigt serait contre productif ? On écrit le code (et sa documentation) une fois, et on les lit des dizaines de fois. Et ça serait contre productif de faciliter cette lecture ?
Je rappelle que dans mes articles, les parties deux font souvent référence (ou du moins tiennent compte) des parties une, les parties trois aux parties une et deux. Ainsi de suite.
Ce qui est contre-productif ce n’est pas d’écrire de la documentation, mais d’écrire le genre de documentation décrite et citée en exemple dans la partie précédente de l’article. C’est de vouloir absolument écrire de la documentation inutile et redondante uniquement pour atteindre le 100 % de couverture.
Un projet couvert par les commentaires à 100 % est génial si 100 % de ces commentaires sont des commentaires utiles. Par contre, si ce sont des commentaires inutiles, que valent ces 100 % ?
Étouffe le code ? L’auteur nous a expliqué dans la partie précédente qu’il ne les voyait plus, ces commentaires/documentation, qu’ils devenaient invisibles pour lui. Je ne comprend pas comment ça peut-être à la fois invisible et étouffant.
Les commentaires inutiles deviennent invisibles parce qu’ils étouffent le code.
Je n’ai sûrement pas été assez clair dans l’article précédent et je ne vais peut-être pas l’être ici non plus, mais je vais essayer de me réexpliquer.
- Tout est commenté dans le projet : bien.
- Tous les commentaires que je lis sont inutiles : je ne les lis plus.
- Ils se mettent à gêner ma lecture du code puisque je ne veux plus les lire : ils étouffent le code.
- Mon cerveau apprend à ne plus y faire attention : ils deviennent invisibles. Pas besoin d’IDE pour ça.
Si ce n’était que ça, ça ne me dérangerait presque pas. Mais, si j’ai un problème, un bug à résoudre et que dans ce cas précis le commentaire qui accompagne le code que j’étudie est utile, contient une information capitale, je ne le verrai peut-être pas puisque mon cerveau a pris l’habitude d’ignorer les commentaires.
Du coup, pourquoi absolument vouloir une couverture de 100 % si à cause de la faible qualité de mes commentaires plus personne ne les lit ?
"Là où le code est propre le commentaire ne sera qu’une redondance sans grand intérêt"
J’ai démontré le contraire.
Non. Le contexte de cette citation ajoute "En forçant les développeurs à écrire de la documentation partout nous les forçons à écrire de la documentation de piètre qualité." devant.
Xavier a démontré que c’était faux si le commentaire est de bonne qualité, mais je n’ai pas dit le contraire.
"Là où le code est propre, le commentaire ne sera qu’une redondance sans grand intérêt" si nous forçons, par le code mandaté, les développeurs "à écrire de la documentation de piètre qualité."
si il n’y a pas de code review c’est pas d’écrire ou non de la doc qui va changer grand chose à la propreté du code. Et dans ce cas la responsabilité irait à l’auteur du code, pas à la documentation.
On est d’accord.
Pour aller plus loin :
Rejoins 250+ développeurs de notre liste de diffusion et sois reçois les articles directement dans ta boite mail.
Aucun spam. Désabonnes-toi en un seul clic à tout moment.
Si vous avez des questions ou des remarques/conseils, n'hésitez pas à laisser un commentaire plus bas ! Je serais ravis de vous lire. Et si vous aimez l'article, n'oubliez pas de le partager avec vos amis.