Veuillez garder les explications de code simples

• Lors d’une revue de code, quand de longues explications arrivent avec un gros diff, il devient difficile pour la personne qui relit d’identifier la raison essentielle du changement ; les messages de commit, descriptions de merge request et commentaires doivent donc rester concis
• Les explications doivent se concentrer sur le pourquoi du changement plutôt que sur ce qui a changé, car une grande partie des modifications peut être vérifiée directement dans le code
• Les longues explications qui tentent d’inclure tout le contexte d’un seul coup peuvent nuire à la concentration de certain·es relecteurs et ralentir la revue
• Dans une revue avant fusion, les commits atomiques sont particulièrement importants ; les petites corrections peuvent être gérées avec git amend, et le nettoyage avant fusion via rebase ou squash
• Même si l’on utilise des outils LLM, il est préférable d’écrire soi-même les commentaires, explications et messages de commit, car cela aide davantage à comprendre le code et à rendre la revue plus accessible

---

En revue, privilégier le « pourquoi » plutôt que le « quoi »

• En revue de code, lorsque les explications, commits et merge requests sont remplis d’informations excessives, la charge de relecture augmente
• Au lieu d’énumérer longuement les changements, l’essentiel est d’écrire clairement pourquoi ils ont été faits
• Le code lui-même peut montrer la plupart des modifications, et si le contexte manque, la personne qui relit peut poser des questions
• Des explications rédigées comme de longs textes peuvent ralentir la revue pour les personnes qui ont du mal à maintenir leur concentration
• Les messages de commit, descriptions de merge request et commentaires de code gagnent à rester clairs, centrés sur l’essentiel et limités aux informations nécessaires

Demande sur l’organisation des commits et l’usage des LLM

• Les commits doivent être particulièrement atomiques lors d’une revue avant fusion, et chaque changement doit pouvoir être compris indépendamment
• Les petites corrections peuvent être intégrées avec git amend, puis nettoyées avant fusion avec un rebase ou un squash
• Même en utilisant des outils LLM, il vaut mieux rédiger soi-même les commentaires, explications et messages de commit
  • Le fait d’écrire soi-même aide à mieux comprendre les changements
  • Des explications rédigées directement peuvent être plus faciles d’accès pour la personne qui relit
• L’auteur exprime aussi l’avis personnel qu’il vaut mieux éviter les outils LLM autant que possible
• Il y a eu des réactions au terme d’accessibilité, mais l’idée centrale reste de rendre les explications de revue de code plus concises et plus faciles à relire

[GN⁺]

Avis sur Lobste.rs

• Il faut faire attention à ne pas assimiler trop facilement des besoins d’accessibilité à de simples préférences personnelles.
  Le fait d’avoir un TDAH ne veut pas dire qu’il est universel chez les personnes TDAH de détester les longs messages de commit, et l’accessibilité ne consiste pas à « faire tout ce que préfèrent les personnes avec un TDAH », mais se rapproche plutôt d’aménagements raisonnables qui n’imposent pas une charge excessive aux utilisateurs en général.
  C’est pour cela que beaucoup de fonctions d’accessibilité se trouvent derrière des réglages que chacun peut choisir, comme le contraste élevé, la réduction des animations ou le mode sombre.

  • J’aurais pu l’écrire plus clairement, mais mon AuDHD a besoin de certaines conditions pour pouvoir fonctionner correctement.
    De gros blocs de texte, par exemple quand un petit changement s’accompagne de deux pages A4 d’explications, peuvent complètement me bloquer dans mon travail, et me forcer à les lire peut mener au burnout.
    J’aurais sans doute dû le formuler comme « c’est un de mes besoins d’accessibilité, et je sais que beaucoup d’autres personnes ressemblantes existent ».
    On peut malgré tout considérer cela comme une préférence plutôt qu’un besoin, mais quand vous collez des murs de texte générés par des LLM dans des messages de commit, pensez aussi à des gens comme moi.
  • Cela varie selon les personnes, mais le fait de « dire l’essentiel d’abord » me semble être un trait central du TDAH assez fréquent.
    Même du point de vue de l’accessibilité, tout le monde profite de cet aménagement, donc il n’y a pas vraiment de raison de s’y opposer.
  • D’après mon expérience, une bonne partie des difficultés inutiles rencontrées par les personnes neurodivergentes et handicapées vient du fait qu’on réduit les besoins d’accessibilité à de simples préférences.
    Quand l’accessibilité augmente, même ceux qui n’ont pas absolument besoin de ces fonctions pour partir sur un pied d’égalité en tirent aussi profit, donc aller dans cette direction est une bonne chose.

• Bien avant l’IA, j’ai toujours préféré des commentaires excessivement détaillés, et beaucoup de gens avec qui j’ai travaillé en étaient surpris.
  Par exemple, il y a cette méthode : https://github.com/ghostty-org/ghostty/…
  Depuis 15 ans, quelle que soit la langue, j’écris globalement dans ce style, et à l’ère de l’IA j’ai même précisé cette approche dans AGENTS.md.
  Le fichier et les commentaires liés sont entièrement écrits par des humains, sans aucune IA.
  La raison est simple : cela impose une règle de double saisie selon laquelle le commentaire et le code doivent correspondre.
  S’ils ne correspondent pas, alors soit le commentaire est faux, soit le code est faux, soit les deux le sont, et le simple fait de se demander « lequel des deux est correct ? » m’a permis de repérer beaucoup de problèmes.
  Au final, sur son propre projet, chacun devrait commenter comme il le souhaite.

  • On me taquine parfois gentiment en disant que j’écris plus de commentaires que de code, mais j’adore vraiment ce genre de commentaires.
    Quand je relis le code plus tard, ils préservent le contexte des décisions locales prises à l’époque, et ils aident aussi les reviewers ou les nouveaux venus à reconstruire ce contexte.
    Ce genre de commentaires est certes verbeux, mais ne correspond pas aux « détails inutiles » visés dans le billet, et l’exemple partagé me semble être un bon cas du principe « expliquer le pourquoi, pas le quoi ».
  • Ces commentaires sont excellents.
    Comme dans l’exemple, un commentaire qui explique pourquoi les utilisateurs macOS mettent leur configuration shell dans ~/.bash_profile et s’attendent à un shell de connexion fournit un contexte utile sur la raison d’une décision donnée.
    En revanche, pour revenir aux LLM, je n’ai encore jamais vu personnellement de commentaires générés par LLM de cette qualité.
    En général, ils se contentent de répéter des choses évidentes à la simple lecture du code, du style faire foo(), puis bar(), puis enfin baz.
  • Les commentaires du type de ceux mis en lien ne posent aucun problème.
    Le vrai problème, c’est le chaos qui consiste à coller d’énormes tableaux et listes à puces même pour des changements minuscules.
  • Je suis vraiment reconnaissant pour ce niveau de détail, mais personnellement je préfère qu’il figure dans le message de commit du commit qui a ajouté cette méthode plutôt que dans les commentaires.
    Les messages de commit restent une trace toujours synchronisée avec le code à ce moment-là, alors que les commentaires peuvent finir par diverger avec le temps.
  • Le commentaire qui commence à la ligne 1467 est un chef-d’œuvre, on y sent toute la fatigue.

• Au travail, j’ai essayé d’ajouter poliment dans le template de PR : « merci d’expliquer directement la motivation de ce changement et les décisions de conception importantes à examiner pendant la review ».
  Pourtant, 9 fois sur 10, le LLM du moment efface tout le template et recrache une longue explication avec le nombre de tests ajoutés, des cases à cocher de validation et de longues digressions sans importance.
  Ce qui rend bien sûr les reviews extrêmement agréables.

  • J’ai le même problème au travail.
    Je ne sais pas qui s’est dit que c’était une bonne idée d’ajouter partout des outils de génération de messages de commit par LLM, mais au final on se retrouve avec le problème https://noslopgrenade.com/ dans les commits.
    Les messages de commit ou descriptions de pull request n’apportent plus le contexte utile — motivation du changement, décisions de conception, justification — et se transforment en paragraphes décrivant l’implémentation dans le détail alors qu’il suffit de lire le code.
  • J’ai vu exactement le même comportement.
    J’envisage d’ajouter dans agents.md une consigne disant : « quand vous rédigez un message de commit, référez-vous à commit-messages.md ».
    Dans commit-messages.md, on pourrait mettre des règles pour les messages de commit comme l’interdiction des cases à cocher réussite/échec des tests, ou le fait de résumer les tests individuels au lieu de tous les lister, voire de ne rien écrire du tout à leur sujet.

• Si j’écris en commentaire ce que je suis en train de faire, ce n’est jamais pour expliquer pourquoi, mais uniquement quand je ne suis pas sûr que cette manière soit la bonne.
  L’une des grandes sources récurrentes de souffrance, ce sont les expressions régulières.

  • Moi aussi.
    Il y a des moments où tout doit être solidement expliqué, mais aujourd’hui je vois même des explications énormes attachées à de petits changements comme un simple renommage de variable.

• Fait intéressant, on m’a au contraire souvent dit que mes messages de commit étaient trop courts.

  • La discussion de ce billet va dans l’autre sens, et fait écho au billet Chesterton middle finger, qui se plaint que les explications sont trop courtes.
  • On peut être trop bref, mais y mettre tout un roman n’a pas plus de sens.
  • Les LLM écrivent vraiment beaucoup trop.
    C’est pourquoi j’ai configuré claude pour qu’il n’écrive jamais de commentaires, parce qu’ensuite j’en supprimais manuellement 98 % et je réécrivais encore les 2 % restants.

• J’aime généralement les messages de commit très explicatifs, mais je préfère une structure de type article de presse, où l’on place d’abord les informations les plus importantes, puis les détails moins importants mais toujours pertinents ensuite
  Par exemple, le titre concentre autant que possible l’information essentielle, le premier paragraphe explique les changements dans des phrases moins condensées, et les paragraphes suivants contiennent des détails supplémentaires sur la nature des modifications du code qu’il n’est pas nécessaire de lire en détail à moins qu’ils ne soient vraiment difficiles à comprendre
  J’ai l’impression qu’on sous-estime à quel point les messages de commit sont importants pour les personnes qui liront le code plus tard
  Quand on fouille dans une base de code et qu’on se demande pourquoi un bloc a cette forme, je n’ai jamais été déçu de tomber, via git blame, sur un message de commit qui explique avec un luxe de détails qu’une approche apparemment maladroite était en réalité le choix restant après plusieurs approches meilleures en apparence mais incomplètes
  Pour revenir au point principal de l’auteur, ajouter des balises explicites dans la communication est un bon ajustement et c’est utile de manière générale
  On peut insérer au milieu d’un message de commit une phrase du genre « si vous êtes en train de relire ce code, vous pouvez arrêter votre lecture ici »

• Dire que « les détails inutiles pourront être demandés si besoin » suppose assez audacieusement que cette personne sera encore là
  J’ai commencé à écrire des messages de commit avec soin en commençant à contribuer à une base de code FLOSS vieille de plus de 10 ans
  Le seul moyen d’en apprendre davantage sur les raisons de l’existence du code était l’archéologie git, et j’ai appris à utiliser vc-annonate d’Emacs pour faciliter le suivi
  Même dans du code en entreprise, il m’est arrivé plusieurs fois que l’auteur d’origine d’une base de code que je maintenais soit déjà parti depuis longtemps
  Les messages de commit ne sont pas lus uniquement pendant la review, et d’ailleurs beaucoup d’interfaces de review masquent les messages de commit
  Le problème semble moins être les longs messages de commit en eux-mêmes que les messages de commit mal rédigés
  La recommandation « les messages de commit, les descriptions de merge request et les commentaires de code doivent être écrits de façon claire, orientée vers l’essentiel et selon les besoins, et doivent expliquer le pourquoi plutôt que le quoi » me paraît bonne
  Le problème vient peut-être du fait qu’une personne qui écrivait auparavant seulement Fix Bugz 🚀️ se mette désormais à rédiger ses messages de commit avec un LLM au nom des « bonnes pratiques »
  Mon hypothèse est que si la plupart des gens n’écrivent pas de messages de commit, c’est parce qu’ils ne les lisent pas, et qu’ils ne les lisent pas parce que l’énergie d’activation nécessaire pour les consulter est élevée lorsqu’on parcourt les commits en s’appuyant sur des outils comme l’interface web de GitHub

  • « les détails inutiles pourront être demandés si besoin » concerne la phase de review
    Si l’information est importante, on peut la laisser dans un commentaire ou l’ajouter au message de commit
    KDE utilise Gitlab depuis plusieurs années

• À long terme, il faut un équilibre pour réussir l’archéologie git avec les générations suivantes
  Avec le turnover et la disparition du contexte des esprits, il est souvent impossible plus tard de demander ces détails qui semblaient superflus au départ
  Le meilleur moment pour consigner ce contexte, c’est quand on l’a encore
  Ce qu’on veut vraiment, c’est peut-être mettre d’abord les détails importants et les distinguer clairement, comme dans un aperçu

• Une PR ou une explication de code sert à expliquer pourquoi on a fait quelque chose, pas ce qu’on a fait
  Il faut dire pourquoi le code a cette forme et quelles sont les raisons derrière
  C’est utile pour la review, et plus tard aussi pour retrouver dans l’historique git pourquoi le code a été écrit ainsi

• Garder les explications de code simples est important
  Parce que ce qu’on ne peut ni comprendre ni suivre ne peut pas être lu
  En même temps, quand on développe du logiciel, beaucoup de contexte disparaît, et aujourd’hui ce contexte n’existe souvent plus que dans la tête de l’auteur, de ceux qui en ont parlé avec lui ou de ceux qui ont étudié le code en profondeur
  Mais je pense que ce contexte devrait être davantage lié au code, pas moins
  Comme on ne peut pas toujours parler à l’auteur, il faut l’écrire quelque part d’accessible en permanence et mis à jour avec le code
  Dans la plupart des flux de développement actuels, l’endroit le plus adapté pour cela est le message de commit git
  Écrire un résumé en haut est une bonne chose, mais je recommande aussi de laisser des explications supplémentaires sur les modifications du code
  Si l’on externalise le contexte, y compris ce qui ne semble pas important sur le moment, notre futur nous en sera reconnaissant
  À l’avenir, il faudra une meilleure approche que de mettre ce contexte uniquement dans les messages de commit, et c’est pourquoi, personnellement, j’aime la programmation lettrée, qui offre plus d’espace pour expliquer le « quoi » et le « pourquoi » du code