Pourquoi ne pas faire de commentaires « pourquoi pas »

• Pourquoi pas des commentaires « pourquoi pas » ? Pas pourquoi « pas de commentaires »
  • « Pourquoi ne laissez-vous pas de commentaire sur pourquoi ça n’a pas marché ? Je ne vous demande pas pourquoi vous n’avez pas mis de commentaires. »

Pourquoi pas des commentaires « pourquoi pas »

• Le code est écrit dans un langage machine structuré, tandis que les commentaires sont rédigés dans un langage humain riche en expressions
• Cela signifie qu’il ne faut pas commenter le « quoi », mais inclure autant d’informations que possible dans les identifiants
• Récemment, certains ont même soutenu qu’il ne fallait pas non plus mettre le « pourquoi » dans les commentaires, mais l’inclure dans des LongFunctionNames ou dans les noms des cas de test
• Une base de code « auto-documentée » ajoute sa documentation à travers les identifiants

Exemple récent

• Exemple tiré de Logic for Programmers
• Un problème est survenu lors de la génération de l’epub : les symboles mathématiques (\forall) n’étaient pas convertis en symboles (∀)
• Un script a été écrit pour remplacer manuellement les tokens des chaînes mathématiques par de l’Unicode
• Le script a été rédigé de manière à remplacer séparément 16 symboles mathématiques, mais cette approche est inefficace
• Le problème a été résolu simplement en ajoutant un commentaire
  • « On répète 16 fois pour chaque chaîne, mais le livre ne contient actuellement que 25 chaînes mathématiques et la plupart font moins de 5 caractères, donc c’est encore largement assez rapide »

Pourquoi il faut ajouter des commentaires

• Pourquoi il faut ajouter des commentaires même si du code lent ne cause pas encore de problème
• Le code pourrait devenir problématique à l’avenir
• Les commentaires montrent qu’on a conscience des trade-offs
• Quand on reviendra plus tard sur le projet, on pourra comprendre pourquoi du code lent a été écrit

Pourquoi l’auto-documentation est impossible

• Des noms de fonction longs comme RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs n’expliquent pas les trade-offs
• Les identifiants de fonctions et de variables ne peuvent contenir qu’un seul type d’information
• Il est également impossible de remplacer les commentaires par des tests
• L’auto-documentation explique ce que fait le code, tandis qu’une information négative explique ce que le code ne fait pas

Spéculation à la fin de la newsletter

• L’auteur se demande si l’on peut considérer les commentaires sur « pourquoi ça ne marche pas » comme des cas contrefactuels
• Les abstractions de la communication humaine rendent-elles l’auto-documentation impossible ?
• Peut-on auto-documenter les métaphores, l’incertitude, les arguments éthiques, etc. ?

---

Résumé de GN⁺

• Cet article traite de l’importance des commentaires dans le code et de leurs limites
• Les commentaires permettent de clarifier les trade-offs du code et de faciliter la maintenance future
• Il souligne les limites de l’auto-documentation et la nécessité des commentaires

[GN⁺]

Avis Hacker News

• Quand on ajoute des commentaires au code, il faut surtout expliquer le « pourquoi » et le « pourquoi ça ne marche pas ». Dans le cas d’un code complexe, il peut aussi être utile d’expliquer brièvement le « quoi »

  • Les commentaires obligatoires sont inefficaces, et commenter chaque fonction est une perte de temps
  • Les commentaires ajoutés automatiquement par des outils sont eux aussi inefficaces

• Les ingénieurs juniors écrivent des commentaires qui expliquent ce que fait le code, les ingénieurs intermédiaires expliquent pourquoi il a été écrit ainsi, et les ingénieurs seniors expliquent pourquoi il n’a pas été écrit autrement

• Utilisation d’un modèle de commentaire pour les mainteneurs

  • « Ce code est écrit ainsi pour <raison>. Si vous essayez de le modifier puis réalisez que c’était une erreur, veuillez incrémenter le compteur pour la personne suivante : total_hours_wasted_here = n »

• Il est important d’ajouter des commentaires sur les parties surprenantes du code

  • Lorsqu’on n’est pas sûr que le code sera compréhensible plus tard, on écrit un commentaire expliquant « pourquoi ça ne marche pas »

• L’importance des commentaires est soulignée, surtout lorsqu’il faut maintenir son propre code 5, 10 ou 15 ans plus tard

  • Il est important de rester cohérent avec le code existant

• Il est utile d’ajouter des commentaires sur « ce qui n’est pas la solution naïve »

  • Un code inefficace peut poser problème plus tard au moment d’être modifié

• Il est recommandé d’inclure des commentaires dans les noms de fonctions longs ou les noms de cas de test

  • Les commentaires aident lorsque le nom de la méthode n’est pas clair
  • Si la description d’une méthode contient « et », c’est souvent le signe qu’elle fait trop de choses

• Il peut aussi être utile d’ajouter, via le logging de débogage, un avertissement lorsque l’entrée dépasse les contraintes prévues dans la conception initiale

• Certains préfèrent utiliser beaucoup de commentaires et de commentaires de documentation

  • Ils écrivent des commentaires par étape de l’application, puis les affinent au fur et à mesure qu’ils écrivent le code
  • Ils préfèrent commenter toutes les fonctions et toutes les variables

• Lors des revues de code, ils écrivent des commentaires du type « la raison pour laquelle X n’a pas été fait est Y » afin de prévenir à l’avance les critiques prévisibles