Guide pour écrire de bons commentaires de code

• Rôle des commentaires de code :

  • Les commentaires de code ne servent pas seulement à expliquer « ce que fait le code que l’on a écrit », mais aussi à documenter les choix de conception, les compromis et autres réflexions
  • Ils permettent ainsi d’expliquer « ce que l’auteur du code a fait, et pourquoi il l’a fait ainsi »
  • Les commentaires de code aident à partager le contexte des décisions prises pendant l’écriture du code
  • Ils transmettent des informations sur le code qu’il est difficile d’exprimer avec le seul code

• Importance des commentaires de code :

  • Des commentaires inline placés avant un code complexe font gagner du temps aux autres développeurs qui reliront ce code plus tard
  • À mesure qu’un projet évolue, conserver le contexte des décisions de code passées aide les autres développeurs
  • Si le code est complexe, il faut au moins un court commentaire inline d’une ligne avant celui-ci
  • Il existe des limites à ce que le code seul peut transmettre, notamment le contexte des décisions et diverses autres informations

• Comment écrire de bons commentaires de code :

  1. Rester concis
     • Écrire des commentaires uniquement lorsque c’est nécessaire, en n’incluant que les informations essentielles
       • lorsque le code est inévitablement complexe
       • lorsqu’on ajoute des détails pour améliorer la précision
       • lorsqu’il manque du contexte (par exemple, lors de l’utilisation de code provenant d’un autre dépôt ou package)
     • Réduire la confusion et l’ambiguïté dans les commentaires, et fournir un contexte et des informations utiles
  2. Utiliser les commentaires TODOs/FIXMEs
     • Les commentaires TODOs/FIXMEs sont un moyen d’indiquer qu’« une partie spécifique du code n’est pas terminée ou doit être corrigée »
     • On peut écrire avant une fonction quelque chose comme « TODO: il faut ajouter la fonctionnalité XX »
     • Quand, en écrivant du code, on se dit « il faudra revoir cette partie plus tard » ou « cette fonctionnalité devra être développée ultérieurement », cette méthode permet d’enregistrer et de suivre ces points
     • Extension utile : TODO Highlight
  3. Ne pas se justifier à travers les commentaires
     • Plutôt que d’ajouter des commentaires pour excuser un code erroné ou peu clair, mieux vaut réécrire le code
     • Certains morceaux de code doivent être expliqués par des commentaires, mais d’autres doivent parler d’eux-mêmes, sans dépendre des commentaires
  4. Utiliser l’IA
     • Un générateur de commentaires par IA permet de créer des commentaires dans un format cohérent selon un standard donné
     • Cela aide à maintenir la cohérence des commentaires dans l’ensemble du projet et améliore la lisibilité du code
     • Générateur de commentaires IA utile : Readable

[penza1]

Si des commentaires semblent nécessaires,
on peut peut-être se demander si le code n’est pas en cause.

Des commentaires qui n’évoluent pas avec le code et son cycle de vie ou ses fonctionnalités peuvent aussi semer la confusion pour les développeurs qui les liront plus tard, ou pour soi-même.

Même si le contexte passé n’a plus de rapport avec le présent, ou qu’il a provoqué des erreurs,
les phrases liées à cet ancien contexte peuvent faire hésiter à modifier le code actuel, ou pousser à le contourner pour le résoudre avec une autre structure,
et finir par provoquer encore plus d’erreurs...

D’après mon expérience, les commentaires qui permettent de comprendre pourquoi quelque chose était juste à l’époque mais est faux aujourd’hui sont assez rares....

[ironlung]

Merci beaucoup d’avoir partagé votre précieux avis. En réfléchissant à ce que vous avez dit, je me dis qu’il est aussi nécessaire, pour faire évoluer le code, de s’efforcer de réexaminer avec soin la nécessité des commentaires. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

En regardant ça, j’essaie moi aussi de ne pas écrire trop de commentaires.

[ironlung]

Merci de partager cette excellente vidéo ! :)

[iamchanii]

Même si les routes sont parfaitement aménagées, je pense que des panneaux indicateurs restent indispensables. C’est pourquoi, ces derniers temps, j’essaie de prendre l’habitude d’écrire des commentaires.

[ironlung]

Merci de partager vos réflexions en commentaire. En repensant à ce que vous avez dit, je me rends compte que les commentaires de code relèvent eux aussi d’une forme importante de rédaction technique, ce qui m’amène à revisiter les principes fondamentaux de l’écriture. :)

[balak]

Je pense que le mieux, c’est d’écrire du code compréhensible même sans commentaires.

[ironlung]

Oui, j’ai aussi l’impression qu’il faut d’abord être solide sur les bases. Merci pour votre commentaire. :)