Sur son blog The Old New Thing, l'ingénieur Microsoft Raymond Chen a précisé la différence entre la description d'une pull request et les commentaires intégrés au code source. La description de PR, explique-t-il, est une déclaration ponctuelle qui sert la revue de code elle-même. C'est un exercice d'écriture persuasive, car sa fonction est de convaincre l'approbateur que la modification doit être acceptée.

Les commentaires dans le code jouent un autre rôle. Ils expliquent le code lui-même : comment appeler une fonction, quels prérequis s'appliquent et d'autres connaissances de ce type. Chen qualifie cette information de durable, car elle reste utile bien après la fusion de la pull request.

The Register ajoute que les messages de commit mériteraient sans doute aussi une place dans la discussion. Le sujet tombe à point nommé, alors que les outils de codage par IA génèrent de gros volumes de pull requests, accompagnées d'annotations parfois douteuses. L'article rappelle des extrêmes plus anciens de la culture du commentaire, d'un collègue dont les commentaires C++ consistaient surtout en excuses adressées aux futurs mainteneurs, à un autre qui refusait toute annotation au motif que le code était auto-documenté. Une annotation moderne plus honnête, suggère l'auteur, pourrait se lire ainsi : écrit par un assistant de codage quelconque, et personne ne sait comment tout cela fonctionne.

Le texte relie aussi le débat à la querelle éternelle entre tabulations et espaces. En 2024, un autre vétéran de Microsoft, Larry Osterman, avait soutenu que les tabulations avaient du sens quand le stockage était rare, mais que les espaces sont aujourd'hui le choix le plus sûr, car elles fonctionnent toujours et restent cohérentes. La position de Chen sur le formatage est plus libérale : peu lui importe comment chacun formate son code source. Son seul conseil pratique est de valider séparément tout reformatage en profondeur, afin que les relecteurs ne soient pas ensevelis sous un diff dominé par des changements de style.

La conclusion revient à la distinction centrale de Chen : la description de PR explique pourquoi une modification mérite d'être acceptée, tandis que les commentaires de code préservent ce dont les futurs programmeurs ont besoin pour comprendre le code.