J'ai supprimé 168 000 lignes de commentaires : mon agent IA ne l'a pas remarqué

Une expérience conduite par Roberto Aranda sur une base de code WordPress-like de grande taille soulève une question que beaucoup de développeurs se posent désormais : les commentaires rédigés dans le code servent-ils réellement aux agents de codage ? L'auteur a retiré environ 168 000 lignes de commentaires d'une copie de son dépôt, soit près d'un tiers du code source selon ses propres termes, puis a confié à Claude Code, piloté par le modèle Opus 5.5 en effort élevé, deux tâches de développement identiques sur les deux versions, trois fois chacune.

Le protocole mérite d'être décrit avec précision. Les deux versions ont été compilées et vérifiées comme identiques hormis les commentaires ; il ne reste que environ 800 lignes de directives nécessaires aux outils, comme les directives de lint ou les en-têtes de plugin. La première tâche, petite, consiste à disposer en mosaïque toutes les fenêtres ouvertes ; la seconde, plus large, consiste à maintenir une fenêtre au premier plan. Chaque résultat a été contrôlé par le lint du projet, les vérifications de types, les tests existants et, pour la tâche plus large, un test caché ajouté après coup. Un juge IA distinct a noté chaque modification sur une grille établie avant les essais, sans savoir de quelle branche elle provenait.

Les résultats sont sans surprise sur la qualité : tous les runs ont réussi l'ensemble des contrôles. Sur la petite tâche, le score moyen est de 18,3 sur 19 avec commentaires contre 19,0 sans ; sur la tâche plus large, 21,7 sur 23 contre 22,0. Ces écarts sont jugés dans le bruit par l'auteur. En revanche, la consommation de tokens varie nettement d'un run à l'autre : sur la tâche large, les trois runs avec commentaires ont consommé entre 8,21 et 10,17 millions de tokens, ceux sans commentaires entre 7,01 et 10,64 millions. Selon les runs comparés, retirer les commentaires peut ainsi sembler renchérir l'agent de 30 % ou le réduire de 31 %. Sur la petite tâche, la baisse moyenne est d'environ 22 % de tokens sans commentaires, ce qui s'explique simplement par un volume de texte à lire réduit.

Un point technique illustre la portée de l'expérience. La tâche large comportait un piège : l'état épinglé doit survivre à un rechargement de page, et la fonction PHP qui sauvegarde la session des fenêtres ignore toute clé inconnue. Tous les runs, avec ou sans commentaires, ont identifié ce problème. L'auteur en tire la conclusion que, pour ce cas précis, la présence d'un commentaire ne changeait pas le résultat.

L'auteur relève lui-même les limites de son travail. Un seul modèle, deux tâches et trois runs par branche permettent d'écarter un effet important des commentaires, pas un effet modeste. La variance intrinsèque des agents, qui n'est pas déterministes, impose par ailleurs de répéter les mesures avant de tirer une conclusion sur les coûts. Le code et les grilles d'évaluation sont publiés en annexe, ce qui permet la reproduction.

La question ouverte, pour les équipes qui utilisent des agents sur du code réel, concerne moins les commentaires eux-mêmes que la documentation qui les entoure. L'auteur annonce une prochaine étude sur la suppression du dossier docs/ et du fichier AGENTS.md, dont l'effet, selon lui, pourrait être différent. En l'état, l'expérience suggère que le choix de garder ou supprimer un commentaire peut se fonder sur son utilité pour les lecteurs humains plutôt que sur son effet supposé sur l'agent.