Rétro-documenter un code legacy avec de la lecture assistée, sous revue humaine

Une application tourne depuis des années. Elle fonctionne. Personne ne sait plus précisément ce qu'elle fait, parce que son auteur est parti et que la documentation, si elle a existé, décrit une version qui n'existe plus. Toute décision devient impossible à instruire : on ne peut ni chiffrer une migration, ni évaluer un risque, ni répondre à la question la plus simple, « qu'est-ce qui casse si on touche à ça ». C'est ce point de blocage que la lecture assistée déplace.

Ce que la lecture assistée change, et ce qu'elle ne change pas

Ce qu'elle change : la première lecture cesse d'être un chantier en soi. Parcourir un module, en produire une description structurée, repérer les dépendances, retrouver où une règle est appliquée, tout cela devient abordable sur un périmètre donné. Ce qu'elle ne change pas : le fait que le résultat soit une hypothèse. Le code dit ce qu'il fait, pas pourquoi il le fait, et une intention métier ne se déduit pas d'une condition imbriquée.

Cette distinction n'est pas une précaution rhétorique, elle détermine la forme du livrable. Un document produit par lecture assistée et non validé n'est pas de la documentation : c'est une liste d'hypothèses datées. Écrite comme telle, elle est utile. Présentée comme une référence, elle devient une source d'erreurs plus difficile à corriger que l'absence de documentation, parce qu'on cesse de se méfier.

Le protocole, en quatre temps

Le quatrième temps est celui qui produit la valeur durable, et c'est celui qu'on saute le plus souvent. Un test de caractérisation ne vérifie pas que le comportement est correct : il constate ce qu'il est aujourd'hui et le verrouille. Sur du code dont on ignore la spécification, c'est la seule référence disponible. Sans lui, toute réécriture se compare à une opinion.

La validation, qui est le vrai travail

Chaque règle extraite se confronte à quelqu'un qui l'utilise. La question n'est pas « le code fait-il ceci », le code est explicite ; la question est « est-ce que ce comportement est voulu, ou est-ce un défaut que tout le monde contourne depuis des années ». Cette réponse ne se trouve nulle part dans le dépôt. Elle se trouve auprès du comptable, du responsable d'atelier ou de l'assistante commerciale qui compose avec l'anomalie tous les jours.

Ce passage transforme un inventaire technique en spécification. C'est aussi lui qui donne sa valeur au reste : une organisation qui sort de cet exercice sait ce qu'elle doit conserver, et peut enfin arbitrer entre maintenir, migrer par briques ou refondre.

Vérifier la méthode avant d'y engager un budget

Un point technique qui évite une déconvenue : la qualité de lecture dépend de la représentation du langage dans les données d'entraînement des modèles. Sur des langages très diffusés, elle est bonne. Sur des langages propriétaires ou peu publics, elle se dégrade sans prévenir, et un texte assuré peut décrire un comportement inexistant.

La parade est simple et ne coûte presque rien : choisissez un module que quelqu'un connaît encore, faites-en produire la description, et comparez. Si la restitution est fidèle sur un terrain connu, la méthode est utilisable sur le reste. Si elle invente sur un module dont vous avez la réponse, elle inventera là où vous ne l'avez pas. Cette vérification se fait avant d'engager quoi que ce soit, jamais après.

Questions fréquentes