Reprendre une application sans documentation : la méthode
01/09/2026
Vous avez récupéré le code. Il compile, l'application tourne, et personne dans votre entreprise ne sait comment elle fonctionne. Aucun schéma, aucune procédure, quelques commentaires épars et un fichier de démarrage qui date d'il y a trois ans.
C'est la situation la plus courante des reprises d'application, et de très loin. La documentation est ce qu'on écrit en dernier, donc ce qu'on n'écrit jamais. Bonne nouvelle : reprendre un code non documenté est un exercice connu, avec une méthode. Mauvaise nouvelle : la méthode consiste à résister à l'envie de tout réécrire pendant les premières semaines.
La règle d'or : comprendre avant de toucher
Le réflexe naturel devant un code inconnu est de commencer par le nettoyer. On renomme, on réorganise, on supprime ce qui semble mort. C'est l'erreur qui coûte le plus cher.
Dans un système que personne ne comprend encore, chaque bizarrerie est potentiellement un correctif appliqué pour une bonne raison, oubliée depuis. Le code étrange est souvent du code cicatriciel : il porte la trace d'un incident réel. Le supprimer rouvre la plaie, généralement en production et généralement un vendredi.
La règle tient en une phrase : on ne modifie rien tant qu'on ne peut pas vérifier que la modification ne casse rien. Tout ce qui suit sert à atteindre ce point.
Étape 1 : faire tourner le projet localement
Le premier objectif n'est pas de comprendre le code, c'est de le faire démarrer sur votre machine. Tant que ce n'est pas fait, rien d'autre n'est possible.
Cette étape révèle immédiatement ce qui manque : variables d'environnement non documentées, services externes indispensables, versions précises d'outils, données de référence sans lesquelles l'application plante au démarrage. Notez chaque obstacle et sa solution au fur et à mesure, car vous êtes en train d'écrire la procédure d'installation que personne n'avait rédigée.
Le jour où un deuxième développeur démarre le projet en suivant vos notes, la première page de documentation existe.
Étape 2 : cartographier avant de lire
On ne lit pas un code inconnu ligne par ligne, on en dresse d'abord la carte. Quatre questions à répondre dans l'ordre.
- Par où entre-t-on ? Les points d'entrée : pages, routes d'API, tâches planifiées, files de traitement. Ils donnent la liste des choses que le système sait faire.
- Où sont les données ? Le schéma de la base, les tables principales et leurs relations. Le modèle de données est la colonne vertébrale : il en dit plus long sur le métier que le code lui-même.
- Qu'est-ce qui sort ? Les appels vers l'extérieur : paiements, courriels, services tiers, notifications. Ce sont les effets de bord, donc les zones où une erreur devient visible ou coûteuse.
- Qu'est-ce qui tourne tout seul ? Les traitements planifiés sont les grands oubliés des reprises. Ils s'exécutent sans que personne les déclenche, et on découvre leur existence quand ils échouent.
Cette cartographie prend deux à cinq jours sur une application de taille moyenne. Elle produit un schéma qui devient le document de référence de l'équipe.
Étape 3 : les tests de caractérisation
Voici la technique centrale, et la moins connue des non-développeurs.
Un test de caractérisation ne vérifie pas que le code fait ce qu'il devrait faire. Il enregistre ce qu'il fait aujourd'hui, correct ou non. On soumet une entrée, on observe la sortie, on fige ce comportement dans un test.
L'intérêt est immédiat : à partir de là, toute modification qui change ce comportement déclenche une alerte. On peut enfin toucher au code, puisqu'on saura si on a cassé quelque chose. Ces tests capturent aussi les bugs existants, ce qui est voulu : ils décrivent l'état de départ, et corriger un bug devient un changement conscient plutôt qu'un effet de bord.
On ne couvre pas tout le système ainsi, ce serait interminable. On commence par les parcours qui portent la valeur : ceux dont la panne coûte de l'argent ou des clients. Le reste vient au fil des interventions.
Étape 4 : reconstituer le métier
Le code dit comment le système fonctionne, jamais pourquoi. Cette information vit dans la tête des utilisateurs, et elle est indispensable avant toute évolution.
Trois sources la restituent. Les utilisateurs quotidiens, d'abord, qui connaissent les règles réelles, y compris les contournements qu'ils ont inventés pour compenser les défauts du logiciel. Les données ensuite, car les valeurs présentes en base révèlent les cas réels et leurs exceptions. Enfin l'historique des versions, quand il existe : les messages de commit racontent souvent les décisions mieux qu'aucun document.
Cette étape se mène en parallèle de la technique, pas après. Un développeur qui comprend le métier prend de meilleures décisions qu'un développeur qui comprend seulement le code.
Étape 5 : documenter au fil de l'eau
La documentation ne se rattrape pas en un chantier dédié, personne ne finance trois semaines d'écriture sans fonctionnalité à la clé. Elle se construit par sédimentation.
La règle pratique est simple : chaque fois que quelqu'un cherche une information plus de dix minutes, elle est écrite quelque part une fois trouvée. Trois documents suffisent au début. Un fichier de démarrage qui permet à un nouveau venu de lancer le projet. Un schéma d'architecture, même dessiné à la main. Un journal des décisions, qui note pourquoi tel choix a été fait, car c'est l'information qui manque le plus dans six mois.
Au bout de quelques mois d'interventions, cet ensemble couvre l'essentiel de ce qu'on aurait mis dans une documentation complète, sans avoir jamais bloqué de budget pour elle.
Le piège de la réécriture
Arrive toujours le moment où quelqu'un propose de tout reprendre proprement. L'argument est séduisant : le code est confus, on le comprend mal, une base saine irait plus vite.
Trois raisons de résister. La réécriture recommence à zéro l'apprentissage du métier, qui est justement ce qui manque. Elle fait perdre les correctifs accumulés, ces bizarreries qui répondent à des cas réels rencontrés en production. Enfin elle immobilise l'évolution pendant toute sa durée, alors que l'activité, elle, continue.
La réécriture complète se justifie parfois, notamment quand la technologie de départ est un cul-de-sac. Mais elle se décide après l'audit, sur des faits, pas pendant les premières semaines d'inconfort. Notre article sur le choix entre reprendre et refaire détaille les critères, et celui sur l'audit de code avant reprise décrit comment les établir.
Quand une réécriture s'impose vraiment, elle se mène par remplacement progressif plutôt qu'en un bloc : on isole une partie du système, on la reconstruit, on bascule, on recommence. L'application reste en service pendant toute l'opération, et chaque étape peut s'arrêter sans perte.
Comment nous entrons dans un code inconnu
Notre première semaine sur une reprise ne produit aucune fonctionnalité, et nous l'annonçons d'emblée. Elle sert à démarrer le projet localement, cartographier le système, et écrire les premiers tests de caractérisation sur les parcours critiques.
Cette semaine est la meilleure économie du projet. Sans elle, chaque intervention ultérieure se fait à l'aveugle, avec un risque de régression à chaque fois, et le coût réel apparaît trois mois plus tard sous forme d'incidents.
Nous livrons ensuite un état des lieux et une première documentation, qui vous restent quoi qu'il advienne de la relation. Puis viennent les corrections, par ordre d'urgence, avant l'entrée en régime régulier de maintenance applicative.
Nous acceptons souvent des applications que d'autres ont refusées, parce que l'absence de documentation n'est pas un problème en soi. C'est un état de départ normal, qui a une méthode. Ce qui nous fait renoncer, ce n'est jamais le désordre, c'est l'impossibilité de vérifier quoi que ce soit : ni accès au code, ni données, ni interlocuteur qui connaisse le métier.
Questions fréquentes
Comment reprendre une application sans documentation ?
En trois temps : faire démarrer le projet localement en notant les obstacles, cartographier les points d'entrée et le modèle de données, puis écrire des tests de caractérisation sur les parcours critiques. Ce n'est qu'ensuite qu'on modifie le code, avec un filet.
Qu'est-ce qu'un test de caractérisation ?
C'est un test qui enregistre le comportement actuel du code, sans juger s'il est correct. Il sert de référence : toute modification ultérieure qui change ce comportement est détectée immédiatement. C'est l'outil de base pour intervenir sans risque dans un code inconnu.
Combien de temps faut-il pour s'approprier une application existante ?
Comptez une à trois semaines pour une application de taille moyenne avant de pouvoir intervenir sereinement. La durée dépend surtout de la taille du modèle de données et du nombre de services externes impliqués, plus que du volume de code.
Faut-il tout réécrire quand le code n'est pas documenté ?
Non, l'absence de documentation n'est pas un motif de réécriture. C'est l'état de départ le plus courant, et il se traite par la méthode. La réécriture se décide sur des critères techniques établis par un audit, pas sur l'inconfort des premières semaines.
Peut-on faire évoluer une application dont personne ne connaît le fonctionnement ?
Oui, à condition de reconstituer les règles métier auprès des utilisateurs et des données avant de coder. Modifier un système sans comprendre pourquoi il fait ce qu'il fait produit des régressions invisibles jusqu'à ce qu'un cas réel les révèle.
Que faire si l'ancien développeur est encore joignable ?
Le solliciter en priorité, même pour une heure ou deux d'entretien enregistré. Une session de questions avec la personne qui a écrit le code vaut plusieurs jours de lecture. C'est la raison pour laquelle il faut organiser une période de recouvrement lors d'un changement de prestataire.