Documenter son code à l'ère de l'IA

Documenter a longtemps été la corvée qu'on repousse : le commentaire jamais écrit, le README resté vide, le changelog bâclé. L'IA change ce point de départ — elle rédige en quelques secondes une docstring, un squelette de README, un résumé de module, un journal de versions. Le gain est réel : elle tue le défaut « aucune doc » et explique un code qu'on découvre. Mais une documentation générée a un défaut discret — elle est plausible. Elle décrit ce que le code semble faire, pas forcément ce qu'il fait, encore moins pourquoi. Et elle se périme en silence à mesure que le code bouge, jusqu'à devenir un mensonge confiant. Documenter à l'ère de l'IA, c'est laisser la machine rédiger le brouillon, puis le valider soi-même contre le système réel — et y ajouter ce que le code ne dira jamais : le pourquoi.

Ce que l'IA fait vraiment gagner sur la documentation

Commençons par le gain, car il est authentique. La documentation souffre d'un défaut par défaut : elle n'existe pas. Écrire un commentaire utile, tenir un README à jour, rédiger un changelog lisible sont des tâches sans gloire, systématiquement sacrifiées à la pression du planning. C'est précisément ce vide que l'IA comble le mieux. Donnez-lui une fonction : elle en propose une docstring décrivant les paramètres et la valeur de retour. Donnez-lui un dépôt : elle en esquisse un README, une arborescence, un « pour démarrer ». Donnez-lui une série de changements : elle en tire un premier journal de versions. Le brouillon n'est plus une page blanche.

Ce gain va au-delà du gain de temps. En abaissant le coût d'écrire, l'IA fait basculer l'arbitrage : là où l'on ne documentait pas faute de minutes, on obtient au moins un point de départ. Elle excelle aussi à expliquer un code inconnu — résumer une couche, traduire un pan hérité, nommer un motif — ce qui rejoint l'orientation utile décrite pour découvrir une base de code avec l'IA. Sur du boilerplate — l'en-tête d'un fichier, la signature d'une méthode simple, la description d'un endpoint évident — la sortie est souvent directement correcte. Il serait absurde de s'en priver. La question n'est donc pas de savoir si l'IA doit rédiger la doc, mais ce qu'il reste à faire après qu'elle l'a rédigée.

Une doc générée est plausible — mais pas forcément vraie, et elle se périme en silence

Le piège n'est pas dans le brouillon ; il est dans ce qu'on en fait. Une documentation d'IA arrive claire, structurée, assurée. Cette fluidité produit un effet trompeur : le texte paraît exact. Il ne l'est pas nécessairement. La synthèse académique A Survey on Hallucination in Large Language Models (Huang et coll., arXiv 2311.05232, à paraître dans ACM Transactions on Information Systems) décrit ce comportement : les modèles tendent à générer « un contenu plausible mais non factuel ». Une docstring peut donc affirmer qu'une fonction valide ses entrées alors qu'elle n'en fait rien — et l'affirmer avec le même aplomb que si c'était vrai.

La cause tient à ce que l'IA lit du code. Elle n'en saisit pas l'intention : elle repère des motifs de surface. L'étude Assessing the Impact of Code Changes on the Fault Localizability of Large Language Models (arXiv 2504.04372) le montre : en modifiant la syntaxe d'un programme sans changer sa logique, les auteurs font échouer les modèles sur des fautes qu'ils localisaient auparavant, dans 78 % des cas ; leur raisonnement, concluent-ils, est « souvent lié à des caractéristiques sans rapport avec la sémantique ». Une doc générée décrit donc ce que le code semble faire au regard de ses motifs, pas ce qu'il fait réellement — le même mécanisme de surface que celui décrit dans la dette de compréhension, ici tourné vers le texte qui prétend expliquer le code.

Mais le risque le plus insidieux n'est pas l'erreur du premier jour : c'est la dérive (Fig. 1). Une documentation est vraie à l'instant où elle est écrite, puis le code avance — un refactor, un nouveau comportement, un paramètre supprimé — et la doc, elle, ne bouge pas. L'écart grandit sans bruit. L'étude Investigating the Impact of Code Comment Inconsistency on Bug Introducing (Radmanesh et coll., arXiv 2409.10781) documente ce phénomène sur les commentaires, forme de documentation adossée au code : « les commentaires deviennent souvent obsolètes, créant des incohérences avec le code correspondant », ce qui « peut égarer les développeurs et introduire des bugs ». Les auteurs mesurent l'effet : un changement incohérent est « environ 1,5 fois plus susceptible de mener à un commit introduisant un bug » qu'un changement cohérent. Une doc périmée n'est pas neutre : elle décrit un code qui n'existe plus, et elle le fait avec assurance. C'est ce qui rend une mauvaise documentation pire que pas de documentation — l'absence prévient qu'il faut lire le code ; la fausse doc, elle, égare.

Le pourquoi : ce que la doc doit porter et que le code ne montre pas

Il y a une raison plus profonde de ne pas confier la documentation à la seule machine : une partie de ce qu'une doc doit transmettre n'est pas dans le code. Le code montre le quoi — la structure, les types, ce que fait chaque ligne, qui appelle qui. Tout cela, un modèle le résume honnêtement, car c'est écrit noir sur blanc. Mais le code ne montre pas le pourquoi (Fig. 2) : pourquoi cette voie plutôt qu'une autre, quelle contrainte de performance ou de compatibilité a dicté ce détour, quelle option a été écartée et pour quelle raison, quel invariant ne doit jamais être cassé. Ces éléments ne se lisent nulle part dans le programme — ils vivent dans les têtes, les tickets, les discussions.

C'est exactement ce que la pratique des Architecture Decision Records a formalisé. Michael Nygard, qui l'a popularisée en 2011, pose le problème sans détour : « l'une des choses les plus difficiles à suivre au cours de la vie d'un projet, c'est la motivation derrière certaines décisions ». Sans ce rationale écrit, dit-il, un nouvel arrivant n'a le choix qu'entre « accepter aveuglément » une décision sans en comprendre la valeur, ou « la défaire aveuglément » sans en mesurer les conséquences. Une décision se documente donc en trois temps : le contexte — « les forces en présence, techniques, politiques, sociales, locales au projet » —, la décision elle-même, et ses conséquences, « toutes les conséquences, pas seulement les positives ». Un modèle qui lit le texte du code ne peut pas retrouver cela : il ne connaît ni les forces en présence, ni l'histoire, ni les arbitrages. Au mieux il en propose une justification vraisemblable ; au pire il en invente une. Le pourquoi est un acte d'auteur, humain : c'est la part de la documentation qui ne se génère pas.

Documenter, c'est décider ce que les futurs lecteurs doivent savoir

Ce volet clôt la deuxième saison de la série, et il en retrouve le fil rouge : le métier glisse de produire vers vérifier et décider. Documenter ne fait pas exception. L'IA raccourcit magnifiquement la production du brouillon — et il faut s'en saisir. Mais elle ne produit pas une bonne documentation à votre place, parce qu'une bonne doc suppose deux choses qu'elle ne peut pas garantir : l'exactitude, qui ne s'établit qu'en confrontant le texte au système réel, et le pourquoi, qui n'est pas dans le code qu'elle lit. Documenter à l'ère de l'IA, c'est donc trancher : décider ce qu'un futur lecteur devra savoir, l'écrire vrai, et le garder vrai.

Ce déplacement fait écho aux autres volets de la saison. Comme estimer une tâche reste un jugement humain que l'outil ne rend pas, comme un prototype n'est pas de la production tant qu'on ne l'a pas durci, comme la revue d'architecture reste humaine parce qu'elle engage des décisions, la documentation reste un acte de décision et de vérification. Et la vérification est ici très concrète : elle passe par la confrontation au comportement réel — la même que celle qui permet, côté outils, de déboguer son code avec l'IA en éprouvant chaque hypothèse plutôt qu'en la croyant. L'IA rédige le brouillon ; à vous de le rendre vrai, de le tenir à jour, et d'y déposer ce que vous êtes seul à savoir.