Les meilleurs commentaires ne s’écrivent pas

J’ai lu plusieurs articles sur les "bons commentaires", j’en ai écrit, je lis des bouquins techniques qui traitent des "bons commentaires" et je travaille sur un projet JavaScript où tout doit être commenté (jsdoc). J’ai revu mon point de vue sur le sujet.

Self documenting code

Ce que j’ai retenu de mes expériences et de mes lectures se résume au titre de cet article.

Les meilleurs commentaires sont ceux que l'on n'a pas besoin d'écrire.

Lorsque l’on a besoin d’écrire un commentaire, le plus souvent, c’est que notre code n’est pas aussi clair et propre qu’il devrait l’être.

Comparez :

function main() {
  let imageName = 'test.png'

  // Get the extension off the image filename  
  let pieces = imageName.split('.')
  let extension = pieces.pop()
}

Le commentaire en lui-même n’est pas une mauvaise chose. Le développeur peut juger que l’on aura plus tard besoin d’un commentaire pour une bonne compréhension de la portion de code. Il met un commentaire, c’est gentil.

Mais ça ressemble beaucoup trop à une excuse : "Mon code est moche / compliqué, mais ce n’est pas grave je vais l’expliquer dans un commentaire" au lieu de le nettoyer.

function main() {
  let imageName = 'test.png'
  let extension = getFileExtension(imageName)
}

Le nom d’une fonction est déjà censé répondre à la question de ce que fait une portion de code. Pourquoi ne pas utiliser cette possibilité ?

Trop de commentaires étouffe le code

Comme indiqué plus haut, sur mon projet actuel, nous avons une obligation de documentation. Tout doit être commenté avec de la jsdoc.

Dans l’absolu, c’est très bien. Mais finalement, la plupart des commentaires écrits sont des commentaires qui n’existent que pour passer les tests. Ils sont redondants & inutiles.

/**
 * Get the extension of the file
 * 
 * @param {string} filename - The filename
 * @return {string} the extension of the file  
 */
function getFileExtension(filename) {
  let pieces = imageName.split('.')
  return pieces.pop()
}

Dites-moi qu’il y a une information dans ce commentaire que vous n’aviez pas en lisant le code !

Au contraire, le fait que la fonction retourne l’extension d’un fichier est répété trois fois : une fois dans le nom de la fonction, une fois dans la description de la fonction et une fois pour la balise @return.

Quelle est la plus-value de ce commentaire ? Aucune.

À force de voir des commentaires inutiles, le cerveau les ignore. Sûrement que ça vous l’a déjà fait aussi ; sur des projets où il y a beaucoup de commentaires et une majorité de commentaires comme celui de l’exemple plus haut, on finit par ne plus voir / lire les commentaires.

Malheureusement, le peu de commentaires intéressants est perdu dans cette masse de bruit et n’est pas plus vu que les autres.

La couverture par la documentation

Comme pour les tests unitaires, il existe aujourd’hui des outils qui permettent de calculer le taux de couverture du code pour les commentaires de documentation.

Comme pour les tests unitaires, on est vite tenté de faire la course au 100 % de couverture.

Et comme pour les tests unitaires, je ne suis pas convaincu que la course en vaille la peine. Pour les tests unitaires, un haut taux de couverture n’est pas fiable et n’est pas un gage de qualité ; pour la documentation un haut taux de couverture est contre-productif et étouffe le code.

En forçant les développeurs à écrire de la documentation partout nous les forçons à écrire de la documentation de piètre qualité.

Là où le code est propre le commentaire ne sera qu’une redondance sans grand intérêt que le cerveau apprendra vite à ignorer. Là où le code est sale le développeur pourra utiliser le commentaire comme une excuse pour laisser le code sale.

J’écris moins de commentaires

... et ce n’est pas plus mal. Le code est plus lisible. Cela me force à faire en sorte que mon code s’explique lui-même : le code est plus propre. Les lecteurs font plus attention au peu de commentaires que je laisse.

Le seul problème que je rencontre aujourd’hui se produit dans le cadre de projets avec une documentation publique autogénérée. Comment éviter la redondance tout en faisant en sorte que la documentation générée à partir de mes commentaires soit complète.

---

Pour aller plus loin, voici un article plus récent qui entre un peu plus en profondeur dans l’explication de l’idée/concept présentée ici. Il fait suite aux remarques et questions des lecteurs :

• La documentation sera toujours utile

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.