Comment récupérer le savoir d'un code ancien après le départ de son auteur

Quand l'auteur d'un ancien système part, le savoir ne disparaît pas d'un seul coup. Une partie reste exécutable dans le code source. Une autre ne subsiste que dans les données de production, les calendriers, les habitudes des opérateurs et les intégrations. Certaines connaissances n'ont jamais été consignées et sont perdues. Une reconstruction sérieuse sépare ces catégories au lieu de prétendre qu'une lecture assez intelligente du code peut tout retrouver.

Le but n'est pas d'expliquer chaque fonction. Il faut reconstruire un récit étayé de ce que fait le système, du comportement dont dépend l'entreprise et des incertitudes qui restent. J'ai vu des équipes passer des mois à annoter des branches mortes alors que le véritable contrat se trouvait dans un dépôt de fichiers nocturne et la feuille de calcul d'un comptable. Commencez par les preuves, conservez les contradictions et exigez du remplaçant qu'il démontre l'équivalence là où elle compte.

Le code montre le mécanisme, pas tout le contrat

Le code source peut révéler le flux de contrôle, les transformations de données, les règles de validation, les calculs, les formats de messages, les accès à la base et l'ordre des appels aux systèmes externes. Il répond souvent à des questions précises: quelles valeurs de statut bloquent la facturation? Comment les intérêts sont-ils arrondis? Quels champs rendent un enregistrement admissible à l'export? Quand une nouvelle tentative s'arrête-t-elle? Ces faits se prêtent bien à une extraction automatique.

Le code seul ne dit pas si une règle observée correspond à la politique actuelle, à un ancien contournement ou à un défaut auquel les utilisateurs se sont adaptés. Une branche qui applique un traitement fiscal différent à la catégorie de clients 17 prouve que le programme le fait. Elle ne prouve pas pourquoi cette catégorie existe, si l'exception reste légale ou si quelqu'un crée encore ces clients. Les commentaires règlent rarement la question. Ils peuvent décrire la règle voulue à l'origine alors que la production suit un chemin modifié depuis dix ans.

Séparez trois notions. L'implémentation désigne ce que la source peut exécuter. Le comportement observé décrit ce que le système déployé a réellement fait avec des entrées et dans des conditions données. L'intention métier est la raison pour laquelle quelqu'un voulait ce résultat. Une réécriture a besoin des deux premières pour maintenir le service, mais seules des personnes, des règles, des contrats ou des décisions contemporaines peuvent établir la troisième. Confondre intention et implémentation transforme des accidents en exigences. Ignorer le comportement observé casse les consommateurs qui dépendent de ces accidents.

Cette distinction met aussi fin au débat habituel sur le code comme spécification. Le code fait autorité sur les instructions qu'il peut exécuter, sous réserve de la configuration et des dépendances d'exécution. Les preuves de production font autorité sur les possibilités qui se sont effectivement produites. Ni l'un ni l'autre ne prouve ce qui devra se passer l'an prochain. Étiquetez la provenance de chaque affirmation au lieu de forcer un seul artefact à répondre à toutes les questions.

Dressez une carte des preuves avant d'interpréter

Une carte des preuves doit recenser tous les endroits où le comportement du système peut être observé ou contraint avant que quiconque commence à rédiger une documentation narrative. Sinon, le dépôt le plus accessible devient le centre de l'enquête, même lorsque le comportement lourd de conséquences se trouve ailleurs.

Classez les preuves en quatre groupes:

• Éléments exécutables: sources, scripts de compilation, JCL, procédures stockées, expressions de rapports, formules de feuilles de calcul, code généré et binaires déployés.
• Éléments d'exécution: configuration, indicateurs de fonction, définitions de planification, variables d'environnement, schémas de base, files de messages, formats de fichiers et points d'accès aux services.
• Observations: journaux de requêtes, exemples de messages, entrées et sorties de traitements par lots, changements en base, rapports imprimés, tickets d'incident et procédures opératoires.
• Documents d'autorité: contrats, manuels de politique, interprétations réglementaires, demandes de modification approuvées et décisions des responsables du processus.

Consignez l'origine, la période, l'environnement, le propriétaire, la conservation et les lacunes connues de chaque élément. Un journal de production sans sa version de configuration peut tromper. Une copie de base sans date métier peut donner à une logique de clôture une apparence aléatoire. Une arborescence de sources sans le binaire déployé ne prouve pas que le dépôt correspond à la production.

Utilisez un petit registre de preuves plutôt qu'un immense document narratif:

claim: invoices with hold_code R are not exported
status: observed
evidence:
  - export_job.cob lines 1840-1868
  - nightly output sample 2024-01-16
  - scheduler definition AR_EXPORT
contradiction:
  - runbook says only hold_code L blocks export
owner_needed: accounts receivable
confidence: medium

La contradiction est la partie utile. Ne la résolvez pas en choisissant le fichier le plus récent ou la personne la plus affirmative. Reproduisez l'entrée, suivez la branche, contrôlez les sorties historiques et demandez au responsable du processus si l'écart relève d'une politique ou d'une dérive. Le registre rend ce désaccord visible et fournit au prochain examinateur une affirmation réfutable.

Définissez les règles d'accès et de manipulation avant de toucher aux données de production. Les captures peuvent contenir des identifiants, des données personnelles, des détails de paiement ou du texte libre confidentiel. Réduisez les champs, masquez de façon cohérente, limitez l'accès aux preuves brutes et ne conservez une table de correspondance que si la répétition l'exige vraiment. La reconstruction ne justifie pas la création d'une deuxième archive incontrôlée de données sensibles.

La reconstruction statique commence aux frontières

Le moyen le plus rapide de comprendre un système inconnu consiste à cartographier ce qui traverse ses frontières, puis à remonter vers l'intérieur. Commencer par le point d'entrée principal convient aux petits programmes. Dans un ensemble mêlant COBOL, JCL, PL/SQL, code de bureau et scripts planifiés, il peut ne pas exister de point d'entrée unique honnête.

Extrayez d'abord les interfaces: fichiers lus et écrits, tables touchées, messages consommés, routes HTTP, écrans de terminal, arguments de commande, rapports imprimés et noms de tâches planifiées. Pour chaque frontière, relevez le schéma, l'appelant ou le destinataire, le calendrier, le comportement en erreur et le chemin de code qui la traite. Vous obtenez un graphe de dépendances fondé sur les vraies entrées et sorties, pas sur les noms de dossiers.

Une grande partie peut être automatisée. Des analyseurs construisent les graphes d'appels et la filiation des données. L'analyse SQL cartographie les lectures et les écritures. L'extraction de constantes trouve les codes de statut, masques de date, types d'enregistrement, noms de files et chemins de fichiers. La résolution de symboles entre langages peut relier une étape JCL à un programme COBOL, ce programme à une procédure stockée et la procédure à une table. La détection de conditions dupliquées révèle souvent la même règle métier mise en œuvre différemment dans plusieurs canaux.

Les résultats de recherche sont des pistes, pas des conclusions. L'appel dynamique, la réflexion, le SQL généré, les membres de source copiés, les directives de préprocesseur et la configuration d'exécution affaiblissent un graphe statique. Un graphe d'appels ne dit rien non plus de la fréquence. Une branche exécutée pour chaque commande et une autre utilisée pour la dernière fois pendant une migration terminée peuvent sembler aussi importantes. Marquez les arêtes non résolues et mesurez-les plus tard.

L'historique du dépôt aide lorsqu'il s'agit d'un véritable historique et non d'un import massif. Ces commandes donnent une trace compacte d'une règle suspecte:

git log path/to/export.cob
git blame -L 1840,1868 path/to/export.cob
git show <commit>

La sortie utile est une suite de commits, d'auteurs, de dates et de chemins modifiés. Lisez le ticket ou la demande de changement associée si elle existe. Ne déduisez pas une intention métier du nom d'un auteur ou d'un message de commit laconique. Une ligne attribuée à un commit de migration peut précéder le dépôt de plusieurs décennies.

La documentation JCL d'IBM décrit les instructions DD comme l'association entre le nom logique utilisé par un programme et un ensemble de données ou un périphérique externe. Voilà pourquoi l'analyse des frontières compte: lire le SELECT COBOL seul ne révèle pas quel jeu de données de production arrive à cet emplacement. Il faut le JCL déployé, les conventions du catalogue, les paramètres du planificateur et parfois la procédure opératoire pour reconstruire l'entrée réelle.

Le trafic de production révèle le contrat de fait

Les interactions enregistrées en production montrent les entrées réellement reçues et les sorties remises aux consommateurs, y compris les comportements que personne n'a pensé à documenter. Elles constituent la meilleure base pratique d'un banc de parité, à condition de comprendre ce que l'enregistrement exclut.

Capturez aux frontières stables. Pour un service, enregistrez les requêtes normalisées, réponses, codes de statut et effets persistants. Pour un traitement par lots, conservez les fichiers d'entrée, les paramètres, les lignes initiales pertinentes, les fichiers de sortie, les rapports et les écarts en base. Pour une application de bureau, enregistrez les commandes ou actions utilisateur à la frontière du domaine plutôt que les pixels d'une vidéo, sauf si la disposition de l'écran fait elle-même partie du contrat. Remplacez les valeurs volatiles comme les horodatages et identifiants générés par des règles de comparaison, pas par une suppression arbitraire.

Un bon cas de répétition contient assez de contexte pour expliquer un écart:

{"case_id":"export-00418","business_date":"2024-01-31","input_ref":"sha256:...","config_ref":"sha256:...","expected":{"records":418,"rejects":3,"total_minor_units":9021441}}

Les empreintes lient le cas à des preuves immuables sans placer un fichier client complet dans la définition du test. L'objet attendu compare les résultats métier plutôt que l'égalité octet par octet. Si l'ordre des colonnes ou le remplissage d'une largeur fixe compte pour un consommateur, ajoutez une assertion de format distincte.

L'échantillonnage doit être intentionnel. Un trafic aléatoire couvre les chemins courants, mais manque la clôture trimestrielle, les jours bissextiles, les ajustements rétroactifs, les fichiers vides, les longueurs maximales, les annulations et les rares reprises après erreur. Formez des strates autour des événements métier et des conditions de branche. Gardez les cas normaux parce qu'ils révèlent les volumes, puis ajoutez les limites issues de l'analyse du code et de l'historique des incidents. Ne prétendez jamais à une couverture complète parce qu'une grosse capture se répète sans écart.

Le trafic contient aussi des défauts hérités. Si l'ancien service renvoie un statut incorrect qu'une tâche en aval interprète correctement, le corriger pendant la réécriture peut provoquer une panne. Préservez d'abord le comportement, étiquetez-le comme défaut connu et planifiez une modification coordonnée. La parité contrôle la migration, elle n'approuve pas moralement chaque ancien résultat.

Dans Working Effectively with Legacy Code, Michael Feathers décrit les tests de caractérisation comme des tests qui enregistrent ce que le logiciel fait aujourd'hui, plutôt que ce que quelqu'un pense qu'il devrait faire. Le principe convient à la reconstruction, avec une réserve: une suite réussie ne prouve l'équivalence que pour les observations choisies. Elle ne peut retrouver les cas absents de l'échantillon ni démontrer que le résultat actuel est légal.

Le temps, l'état et les opérateurs créent des comportements cachés

Les systèmes avec traitements planifiés, état accumulé ou opérations manuelles ne se reconstruisent pas à partir de couples requête-réponse isolés. Leur sortie dépend de l'heure d'exécution, de ce qui l'a précédée et de l'intervention qui a modifié l'état.

La clôture mensuelle est le piège habituel. Un calcul peut consulter un calendrier métier, traiter les arrivées tardives, rouvrir une période antérieure puis créer des écritures d'équilibrage dans une étape ultérieure. Rejouer le dernier fichier d'entrée sur une base vide donne un résultat plausible mais faux. Conservez une séquence d'instantanés d'état et d'événements à travers la frontière, avec les fuseaux horaires du planificateur et les tables de jours fériés. Testez une période close, une période rouverte et une exécution en échec reprise après des écritures partielles.

Les nouvelles tentatives exigent leur propre modèle. Une tâche peut être techniquement rejouable uniquement parce qu'un opérateur supprime d'abord un fichier marqueur. Un consommateur de file peut dédupliquer dans un processus, puis dupliquer le travail après redémarrage. Une procédure stockée peut valider toutes les mille lignes et laisser un préfixe terminé après un échec. L'analyse statique trouve les validations et les marqueurs, mais seuls l'historique d'exécution et une répétition contrôlée montrent le fonctionnement global de la reprise.

Les opérateurs font partie du système déployé, même si personne n'a voulu cette architecture. Interrogez-les avec des artefacts concrets. Demandez-leur de raconter la dernière exécution en échec, de montrer la commande utilisée, d'expliquer quelle sortie les a alertés et d'identifier la personne appelée avant de relancer. Une question générale comme «Comment fonctionne le rapprochement?» appelle une description bien rangée. La chronologie d'un incident réel révèle contrôles et exceptions.

Transformez ces interventions en états explicites du flux de travail. Consignez les préconditions, la commande ou action écran, l'autorisation, la preuve attendue et le retour arrière. Si le remplaçant automatise l'action, conservez le point de décision et la piste d'audit au lieu de les cacher dans une boucle de nouvelle tentative. Si un jugement ne peut être automatisé sans risque, gardez-le comme tâche humaine nommée avec assez de contexte pour un nouvel opérateur.

Le comportement de l'horloge mérite des tests directs. Repérez les conversions en heure locale, changements d'heure, dates métier, horloges des serveurs de base et fichiers dont la date vient du nom plutôt que du contenu. Figez l'horloge dans les tests quand c'est possible. Dans le banc de parité, ne normalisez les horodatages affichés qu'après avoir vérifié que l'ordre, les heures limites et les dates comptables correspondent encore.

Les exceptions rares portent plus de risque que les chemins courants

Les branches les moins fréquentes codent souvent les conséquences financières, juridiques ou opérationnelles les plus lourdes. L'analyse statique les trouve, mais la hiérarchie des preuves détermine si elles sont des exigences actives, des protections dormantes ou des débris inaccessibles.

Commencez par les conditions liées aux gros montants, actions privilégiées, juridictions, statuts clients, dérogations manuelles, suppressions de données ou messages externes irréversibles. Comparez ces branches aux comptes de production et aux documents de politique. Un compte nul signifie «non observé pendant cette période», pas «inutilisé». Les règles saisonnières et procédures d'urgence peuvent rester valides sans apparaître dans une trace récente.

Un échec classique commence par une branche apparemment morte. L'équipe de remplacement ne voit aucune exécution pendant quatre-vingt-dix jours, la supprime et réussit toutes les répétitions. Six mois plus tard, un ajustement annuel arrive avec un type de transaction créé par un paramètre du planificateur. L'ancienne branche aurait réparti le montant entre deux grands livres et imprimé un rapport d'exception. Le nouveau système accepte l'enregistrement par le chemin par défaut, si bien que les totaux restent équilibrés alors que l'affectation est fausse. Personne ne s'en aperçoit avant le rapprochement avec un relevé externe.

La bonne décision aurait réuni quatre faits: la branche existait, le planificateur pouvait encore produire le type, une procédure annuelle nommait le rapport et la fenêtre d'observation ne comprenait pas l'événement annuel. Aucun ne prouve seul le besoin actuel. Ensemble, ils justifient un test ciblé et une question aux finances.

Ne répondez pas en documentant toutes les branches avec le même effort. Cette recommandation plaît parce qu'elle produit un progrès visible et des pourcentages de couverture propres. Elle est mauvaise parce que mille accesseurs sans conséquence peuvent masquer une règle de règlement dormante. Classez les recherches selon l'impact, l'accessibilité, les conflits entre preuves et la réversibilité. Laissez les références générées mécaniquement au code ordinaire et consacrez l'attention humaine aux erreurs d'interprétation coûteuses à annuler.

La suppression exige une norme explicite. Retirez un chemin uniquement si vous pouvez démontrer qu'il est inaccessible dans la configuration déployée, rendu obsolète par une décision faisant autorité ou contenu sans risque par la surveillance et le retour arrière. Sinon, préservez-le dans le premier remplaçant ou mettez-le en quarantaine avec un déclencheur clair. L'incertitude doit influencer le plan de migration, pas disparaître de la documentation.

Certaines connaissances sont vraiment perdues

Aucune méthode de reconstruction ne peut retrouver une raison non documentée qui n'a laissé aucune trace distinctive. Si deux raisons métier auraient produit le même code, les mêmes données et les mêmes sorties, aucune preuve ne peut révéler celle que l'auteur avait à l'esprit. Prétendre le contraire revient à inventer une histoire.

Les connaissances perdues comprennent souvent les solutions rejetées, contraintes politiques, promesses orales, interprétations d'un règlement ambigu et la raison d'une valeur seuil particulière. Vous pouvez récupérer le seuil exactement et trouver toutes les transactions touchées, sans savoir s'il venait de la loi, de l'appétit pour le risque, d'une limite fournisseur ou d'une concession temporaire. Cette différence compte quand quelqu'un veut le modifier.

Classez les inconnues au lieu de les lisser dans un texte assuré:

• Récupérable: la preuve existe mais n'a pas encore été reliée, comme une colonne inexpliquée remplie par une tâche connue.
• Testable: l'intention est inconnue, mais le comportement actuel peut être mesuré et préservé.
• À décider: la preuve ne peut trancher, un responsable doit donc choisir la future politique.
• Sans conséquence: la réponse ne changerait ni le comportement, ni le risque, ni l'exploitation, ni la conception du remplaçant.

Pour une inconnue à décider, rédigez une décision avec le comportement observé, les interprétations plausibles, les cas touchés, le responsable, la règle future choisie et son traitement pendant la migration. Ne présentez pas le nouveau choix comme un savoir récupéré. Cette honnêteté empêche un futur auditeur ou ingénieur de prendre une nouvelle décision de politique pour un fait historique.

Les absences limitent aussi la confiance. Les journaux peuvent omettre les enregistrements rejetés. Les instantanés de base peuvent montrer l'état final sans les effets intermédiaires. Les tickets privilégient les pannes par rapport au travail ordinaire réussi. Les entretiens reflètent la mémoire et les intérêts présents. Placez ces angles morts à côté des conclusions qu'ils affaiblissent. Un score de confiance sans explication des preuves manquantes ne sert que de décoration.

Une règle d'arrêt fonctionne bien. Poursuivez l'enquête tant qu'une nouvelle preuve pourrait changer une décision d'implémentation ou de politique lourde de conséquences. Arrêtez quand l'incertitude restante a un responsable, un plan de confinement et aucune voie raisonnable vers de meilleures preuves. L'archéologie peut engloutir n'importe quel budget si personne ne précise la décision que les fouilles doivent soutenir.

Transformez les constats en spécification exécutable

La spécification reconstruite doit permettre aux ingénieurs de bâtir et de contester un remplaçant, pas seulement d'admirer un diagramme. Associez des contrats lisibles par machine à de courts textes sur les décisions et l'incertitude.

Pour chaque capacité métier, consignez entrées, sorties, transitions d'état, invariants, résultats d'erreur, calendrier, permissions, dépendances externes et références des preuves. Ajoutez des exemples tirés de cas de production assainis. Placez les règles de calcul dans des tests exécutables, les formats de fichiers dans des schémas, le comportement des API dans des cas contractuels et les décisions des opérateurs dans des définitions de flux. Le texte explique pourquoi une assertion existe et où elle peut rester incomplète.

Organisez la spécification autour des événements métier plutôt que des anciens modules. Un événement «enregistrer un paiement» peut traverser un écran, un programme COBOL, une procédure stockée, un export nocturne et un rapport. Copier l'ancienne arborescence de dossiers dans la documentation cache cette chaîne. Une vue par événement rend la responsabilité et la parité visibles au-delà des frontières techniques.

Donnez à chaque assertion l'un de ces quatre statuts: préserver, modifier volontairement, retirer ou examiner. Une modification volontaire exige un responsable et un plan de déploiement pour les consommateurs touchés. Un retrait exige une preuve d'inaccessibilité. Un examen exige une question bornée et une échéance liée à une décision de construction. Les questions ouvertes ne restent ainsi pas éternellement dans des commentaires.

Faites la revue avec des contre-exemples, pas avec un diaporama. Demandez à l'opérateur de trouver un chemin de reprise manquant. Demandez aux finances une transaction qui franchit une limite de période. Demandez au responsable d'intégration quels enregistrements mal formés il envoie encore. Faites passer ces cas dans l'ancien système lorsque c'est sûr, ajoutez les observations au registre et actualisez les cas exécutables. Les gens se souviennent des exceptions lorsqu'ils réagissent à une entrée et une sortie concrètes.

Gardez la provenance près des tests. Quand une assertion de parité échoue, l'ingénieur doit voir si la valeur attendue vient de l'analyse du code, d'une trace de production, d'un document de politique ou d'une décision du responsable. La réponse change: réparer le remplaçant, questionner l'échantillon ou faire remonter un conflit de politique. Une valeur attendue sans contexte cache ce choix.

Un remplaçant gagne la confiance par une parité mesurée

La reconstruction finale réussit lorsque le nouveau système peut traiter un travail enregistré représentatif, produire les résultats convenus, exposer les différences volontaires et fonctionner malgré les pannes. Un document seul ne peut pas l'établir.

Exécutez les anciennes et nouvelles implémentations sur les mêmes cas assainis. Comparez les sorties du domaine, changements d'état durables, messages externes, catégories d'erreur et preuves opératoires. Ne normalisez que les valeurs dont l'absence de pertinence est prouvée. Classez chaque écart comme défaut du remplaçant, modification acceptée, non-déterminisme à maîtriser ou ambiguïté nouvellement découverte. N'affaiblissez pas une assertion pour rendre le tableau vert.

Ordonnez la migration selon des frontières observables. Un point d'accès de service remplacé progressivement se compare facilement si les requêtes et leurs effets peuvent être reproduits sans risque. Une chaîne de traitements par lots peut demander des sorties fantômes et un rapprochement avant la bascule. Un flux de bureau peut d'abord placer son calcul derrière un service partagé tout en gardant l'ancienne interface. L'architecture peut changer profondément tandis que les cas de parité maintiennent le comportement métier.

C'est ici que l'analyse de toute la base de code et la vérification par le trafic se rejoignent. CodeHero lit en parallèle les arborescences anciennes mêlant plusieurs langages, les réécrit en Go, Rust, TypeScript et Postgres, puis contrôle le comportement avec un banc de parité face au trafic de production enregistré. Chaque projet est livré en moins de 30 jours. L'affirmation raisonnable n'est pas que l'automatisation redécouvre chaque intention disparue. Elle peut récupérer les mécanismes à grande échelle et soumettre les affirmations de comportement à une comparaison répétable.

Conservez le registre des incertitudes après la bascule. De nouvelles preuves apparaîtront lorsque les événements saisonniers se produiront, que des consommateurs oubliés appelleront un point d'accès et que les opérateurs rencontreront d'anciennes exceptions. Surveillez les hypothèses aux conséquences les plus fortes. Quand un cas inconnu apparaît, dirigez-le vers le responsable nommé dans la décision au lieu de laisser un ingénieur deviner pendant l'incident.

Vous ne pouvez pas interroger un auteur absent à travers son code source. Vous pouvez construire mieux: un récit traçable de ce que permet le code, de ce que la production a prouvé, de ce que l'entreprise décide maintenant et de ce que personne ne peut honnêtement savoir. Ce récit se teste, se révise et résistera bien mieux au prochain départ.