Voici une question que j’aime poser lorsqu’on se demande s’il faut ajouter un commentaire dans une section de code: Que puis-je dire qui aiderait la personne suivante à mieux comprendre l’ intention générale du code, de manière à pouvoir mettre à jour, corriger ou l'étendre plus rapidement et de manière plus fiable?
Parfois, la bonne réponse à cette question est qu'il n'y a rien que vous puissiez ajouter à ce stade du code, car vous avez déjà sélectionné des noms et des conventions qui rendent l'intention aussi évidente que possible. Cela signifie que vous avez écrit du code solide auto-documenté, et que l'insertion d'un commentaire nuirait probablement à plus que cela ne serait utile. (Notez que les commentaires redondants peuvent effectivement nuire à la fiabilité du code au fil du temps en ralentissant le décalage avec le code réel et en rendant ainsi plus difficile le déchiffrement de l’intention réelle.
Cependant, dans presque tous les programmes et tous les langages de programmation, vous rencontrerez des points où certains concepts et décisions critiques pris par le programmeur original - par vous - ne seront plus évidents dans le code. C’est à peu près inévitable, car un bon programmeur programme toujours pour l’avenir - c’est-à-dire, pas seulement pour que le programme fonctionne une fois, mais pour que tous les nombreux correctifs, versions, extensions, modifications et ports à venir, et qui sait quoi faire. fonctionne également correctement. Ce dernier ensemble d’objectifs est beaucoup plus difficile et nécessite plus de réflexion pour réussir. Il est également très difficile d’exprimer correctement dans la plupart des langages informatiques, qui sont plus centrés sur la fonctionnalité - c’est-à-dire dire ce que cela fait. version du programme doit faire, maintenant, afin de le rendre satisfaisant.
Voici un exemple simple de ce que je veux dire. Dans la plupart des langues, une recherche rapide en ligne dans une petite structure de données sera suffisamment complexe pour que quelqu'un qui la consultera pour la première fois ne reconnaisse probablement pas immédiatement ce dont il s'agit. C'est une opportunité pour un bon commentaire, car vous pouvez ajouter quelque chose à propos de l' intention de votre code qu'un lecteur ultérieur appréciera probablement tout de suite comme utile pour déchiffrer les détails.
Inversement, dans des langages tels que le langage logique Prolog, l'expression de la recherche dans une petite liste peut être si incroyablement triviale et succincte que tout commentaire que vous pourriez ajouter ne serait que bruit. Un bon commentaire dépend donc nécessairement du contexte. Cela inclut des facteurs tels que les points forts de la langue que vous utilisez et le contexte général du programme.
L'essentiel est la suivante: Penser à l'avenir. Demandez-vous ce qui est important et évident pour vous sur la manière dont le programme devrait être compris et modifié à l'avenir. [1]
Pour les parties de votre code qui sont vraiment auto-documentées, les commentaires ne font qu'ajouter du bruit et aggraver le problème de cohérence des versions futures. Alors ne les ajoutez pas là.
Mais pour les parties de votre code pour lesquelles vous avez pris une décision critique parmi plusieurs options ou pour lesquelles le code lui-même est suffisamment complexe pour que son objectif soit obscur, ajoutez vos connaissances spéciales sous forme de commentaire. Un bon commentaire dans un tel cas est celui qui permet à un futur programmeur de savoir ce qui doit être conservé - c'est le concept d'une assertion invariante, accessoirement - et ce qui est OK pour changer.
[1] Cela va au-delà de la question des commentaires, mais cela vaut la peine d'être abordé: si vous avez une idée très précise de la façon dont votre code pourrait changer à l'avenir, vous devriez probablement aller au-delà du simple commentaire et intégrer ces paramètres. dans le code lui-même, car ce sera presque toujours un moyen plus fiable d'assurer la fiabilité des versions futures de votre code que d'essayer d'utiliser des commentaires pour guider une future personne inconnue dans la bonne direction. Dans le même temps, vous souhaitez également éviter une généralisation excessive, car les humains sont notoirement mal à même de prédire l'avenir, ce qui inclut l'avenir des modifications apportées au programme. Donc, essayez de définir et de capturer les dimensions raisonnables et éprouvées de l’avenir à tous les niveaux de la conception du programme.