J'avais l'habitude de penser que je n'ai pas besoin de commentaires si j'écris du code auto-documenté. Cependant, j'ai réalisé que j'écrivais des commentaires et les ai trouvés vraiment utiles. Pour voir combien de commentaires j'écris et ce qu'ils sont, j'ai écrit un script pour analyser mes commits git au cours des six dernières années. Au total, sept pour cent de mes lignes approuvées contenaient des commentaires. Cet article contient des détails sur ce qui compte comme bons et mauvais commentaires, ainsi que des statistiques supplémentaires sur mon script.
Javadoc est le plus inutile
L'une des raisons pour lesquelles j'étais sceptique à propos des commentaires était la prédominance des commentaires de style Javadoc. Ce style de commentaire existe également dans d'autres langues. Voici un exemple Python que je viens de trouver, mais qui est représentatif de ce style :
Le problème avec la plupart de ces commentaires est qu'ils véhiculent très peu d'informations. Il s'agit souvent de répéter simplement le nom de la méthode et les noms des paramètres en quelques mots. Ces commentaires peuvent être utiles pour les API exposées en externe, mais dans une application où vous avez accès à tout le code source, ils sont pour la plupart inutiles. Si vous vous demandez ce que fait une méthode ou quelle est la plage d'entrée valide pour un paramètre, il vaut mieux simplement lire le code pour voir ce qu'il fait. Ces types de commentaires prennent beaucoup de place mais ne sont pas particulièrement utiles.
Code auto-documenté
Au lieu d'écrire des commentaires Javadoc, il est préférable de tirer le meilleur parti des noms de méthodes et des noms de variables. Chaque nom que vous utilisez peut aider à expliquer de quoi il s'agit et comment il est fait. Une bonne raison d'écrire de nombreuses petites méthodes au lieu d'une grande est que vous avez plus d'endroits pour utiliser des noms descriptifs, que j'ai décrits ici .
Quand commenter
Écrire du code auto-documenté vous aidera à long terme. Cependant, il y a des moments où il est utile d'avoir plus d'informations. Par exemple, un commentaire sur l'utilisation des zones de numérotation dans le code ci-dessous :
Un autre exemple :
Vous pouvez souvent entendre le conseil « écrire des commentaires POURQUOI, pas QUOI ». Bien que cela couvre probablement la plupart de mes commentaires, ce n'est pas ainsi que je pense au moment de commenter. Au lieu de cela, j'écris généralement un commentaire lorsqu'il y a quelque chose de particulièrement délicat, que ce soit dans le domaine ou dans la façon dont la mise en œuvre est effectuée.
Le conseil standard de la foule "aucun commentaire requis" (à laquelle j'ai déjà appartenu) est de réécrire le code afin que vous n'ayez pas besoin de le commenter. Cependant, ce n'est pas toujours possible. Parfois, un domaine est tout simplement trop compliqué. Parfois, l'effort de réécriture du code serait trop important par rapport à l'ajout d'un commentaire.
Une autre plainte concernant les commentaires est qu'ils seront désynchronisés avec le code, ce qui entravera votre compréhension du code, plutôt que de l'aider. Bien que cela arrive parfois, ce n'était pas un gros problème pour moi. Dans presque tous les cas que j'ai analysés, les commentaires étaient toujours valables. Ils ont également été très utiles. Chaque fois que je tombais sur l'un de ces commentaires, j'étais heureux de l'avoir écrit. Il ne faut pas longtemps pour oublier certains détails et nuances du problème que vous résolvez, et avoir un commentaire avec un contexte et des explications supplémentaires était formidable.
Journaux sous forme de commentaires
Parfois, vous obtenez un commentaire gratuit si vous enregistrez un message explicatif. Dans l'exemple ci-dessous, l'instruction log explique ce qui s'est passé, il n'y a donc pas besoin de commentaires.
Analyse des commentaires
Quand j'ai pensé pour la première fois à vérifier le nombre de commentaires dans tous mes commits, j'ai pensé qu'une ligne suffirait pour trouver les commentaires dans tous mes commits Python (je ne commente qu'avec #):
git log --author = Henrik -p | grep '^ + [^ +]' | grep '#' | wc -l
Cependant, je me suis vite rendu compte que j'avais besoin de plus de détails. Je voulais faire la distinction entre les commentaires de fin de ligne et les commentaires de ligne entière. Je voulais aussi savoir combien de « blocs de commentaires » (lignes de commentaires consécutives) j'avais. J'ai également décidé d'exclure les fichiers de test de l'analyse. De plus, je veux m'assurer d'exclure tout code commenté qui s'est retrouvé là (malheureusement, il y a eu plusieurs cas de ce type). J'ai fini par écrire un script python pour faire l'analyse. L'entrée du script était la sortie de git log --author = Henrik -p.
D'après la sortie, j'ai vu que 1299 des 17817 lignes que j'ai ajoutées contenaient des commentaires. Il y avait 161 commentaires de fin de ligne et 464 commentaires d'une ligne. Le bloc de commentaires le plus long était de 11 lignes, et il y avait 96 cas de blocs de commentaires qui avaient 3 lignes consécutives ou plus.
conclusions
J'avais l'habitude de penser qu'écrire des fonctions bien nommées signifierait qu'aucun commentaire n'était nécessaire. Cependant, en regardant ce que j'ai fait, j'ai remarqué que j'avais tendance à ajouter des commentaires à des parties complexes ou peu intuitives du code. Chaque fois que je revisite ces parties du programme, je suis content d'avoir fait l'effort d'ajouter un commentaire - ils ont été très utiles !