Les 10 erreurs à éviter quand on arrive sur un projet legacy
Nouveau poste, nouvelle mission, nouveau client. On vous confie une application existante. Vous ouvrez le code source pour la première fois et… le sol se dérobe. Pas de tests. Pas de documentation. Des fichiers de 2 000 lignes. Des noms de variables en abrégé que seul l’auteur original comprenait — et il est parti depuis 3 ans.
Bienvenue sur un projet legacy.
Ce moment, je l’ai vécu des dizaines de fois en 13 ans de carrière PHP. Et j’ai vu — parfois commis moi-même — les mêmes erreurs, encore et encore. Des erreurs qui ne viennent pas d’un manque de compétences, mais d’un mauvais réflexe face à l’inconnu.
Voici les 10 erreurs les plus fréquentes quand on débarque sur un projet legacy. Et surtout, comment les éviter.
Erreur n°1 : Vouloir tout comprendre avant de toucher quoi que ce soit
Le réflexe classique du développeur consciencieux : « Je vais d’abord lire tout le code pour comprendre l’architecture. »
Sur un projet moderne bien structuré, c’est une bonne idée. Sur un projet legacy de 200 000 lignes sans documentation, c’est une impasse. Vous allez passer 3 semaines à lire du code spaghetti, à ouvrir des classes qui en appellent d’autres qui en appellent d’autres, et au bout du compte, vous n’aurez toujours rien compris.
Ce qu’il faut faire : adopter une approche ciblée. Partez de la fonctionnalité que vous devez modifier. Tracez le flux de bout en bout — de la requête HTTP à la réponse. Ne cherchez pas à comprendre le système entier, comprenez le chemin que vous allez emprunter. Le reste viendra progressivement, au fil des tickets.
Erreur n°2 : Refactoriser dès le premier jour
L’erreur inverse de la précédente. Vous ouvrez un contrôleur de 1 500 lignes, votre œil de développeur s’enflamme, et vous commencez à extraire des services, renommer des variables, réorganiser les méthodes.
C’est noble. C’est aussi extrêmement dangereux.
Sans tests, vous n’avez aucun filet de sécurité. Chaque modification est un pari à l’aveugle. Ce if bizarre en ligne 847 qui vous semble inutile ? Il gère peut-être un cas métier signalé par un client en 2019, et sa suppression va déclencher une cascade de bugs en production.
Ce qu’il faut faire : avant de refactoriser quoi que ce soit, commencez par écrire des tests de caractérisation. Ces tests capturent le comportement actuel du code — bon ou mauvais. Une fois ce filet en place, vous pouvez refactoriser avec confiance. Pas avant.
Erreur n°3 : Ignorer l’historique Git
Le code ne raconte qu’une partie de l’histoire. L’autre partie est dans Git.
Trop de développeurs débarquent sur un projet legacy sans jamais regarder l’historique des commits. C’est comme arriver dans une ville inconnue et refuser de regarder la carte. Les messages de commit (quand ils sont bien écrits), les pull requests, les discussions associées : tout cela constitue une archéologie du projet précieuse.
Ce qu’il faut faire : utilisez git log, git blame, et fouinez dans les anciennes PR. Vous comprendrez pourquoi certains choix ont été faits, qui les a faits, et dans quel contexte. Un git blame sur la ligne bizarre qui vous pose problème peut révéler un commit avec le message « fix bug client Dupont urgence prod » — et soudain, tout s’éclaire.
Erreur n°4 : Ne pas parler aux humains
Le code legacy ne vit pas dans le vide. Il est le fruit de décisions humaines, prises dans un contexte que vous ne connaissez pas.
L’erreur, c’est de rester seul face au code, de ne jamais aller parler aux personnes qui l’ont écrit, maintenu, ou utilisé. Le product owner qui sait pourquoi cette règle métier est tordue. Le développeur senior qui a écrit ce module « en attendant » en 2018. Le support client qui reçoit les mêmes tickets depuis 6 mois.
Ce qu’il faut faire : dès votre arrivée, identifiez les détenteurs de la connaissance métier. Posez-leur des questions ouvertes : « Pourquoi cette fonctionnalité marche-t-elle comme ça ? », « Quels sont les cas particuliers que le code doit gérer ? » Vous apprendrez en 30 minutes de conversation ce que 3 jours de lecture de code ne vous auraient pas révélé.
Erreur n°5 : Appliquer les standards modernes brutalement
Vous venez d’un projet Symfony 7 avec PHP 8.3, des types stricts partout, du DDD, des événements, et une couverture de tests à 85%. Vous arrivez sur une application PHP 7.2 avec du SQL dans les contrôleurs et des global $db qui traînent.
La tentation : imposer d’un coup vos standards modernes. Forcer les types stricts, restructurer en hexagonal, migrer vers Doctrine…
C’est le meilleur moyen de tout casser et de braquer l’équipe.
Ce qu’il faut faire : appliquer la règle du boy-scout : « Laissez le campement plus propre que vous ne l’avez trouvé. » À chaque modification, améliorez un petit peu le code que vous touchez. Ajoutez un type hint ici. Extrayez une méthode là. Écrivez un test pour ce flux-là. La modernisation se fait par couches successives, pas par big bang.
Erreur n°6 : Sous-estimer le code « moche mais qui marche »
Ce code que vous trouvez affreux, illisible, mal structuré ? Il a un avantage que votre futur code propre n’a pas encore : il tourne en production depuis des années.
Il a survécu à des milliers d’utilisateurs, des cas limites imprévus, des montées en charge, des pannes serveur. Chaque ligne « moche » est peut-être là pour une raison. Chaque try/catch englobant cache peut-être un bug corrigé à 3h du matin un dimanche.
J’ai vu un développeur supprimer un bloc de code qu’il jugeait inutile. Ce bloc gérait un cas de concurrence qui ne se produisait qu’une fois par mois, lors d’un traitement batch nocturne. Le bug est revenu 4 semaines plus tard. Il a fallu 2 jours pour le re-diagnostiquer.
Ce qu’il faut faire : partez du principe que chaque anomalie dans le code a potentiellement une raison d’exister. Investiguer avant de supprimer. Comprendre avant de corriger. L’humilité face au code legacy n’est pas une faiblesse, c’est une compétence.
Erreur n°7 : Ne pas mettre en place de CI/CD immédiatement
Pas de pipeline d’intégration continue ? Pas de déploiement automatisé ? Des mises en production manuelles via FTP ?
Si c’est le cas, votre première priorité n’est pas de corriger le code. C’est de sécuriser le processus de livraison.
Beaucoup de développeurs se concentrent sur la qualité du code en ignorant l’infrastructure de déploiement. Mais sur un projet legacy, le risque n’est pas seulement dans le code : il est dans la manière dont ce code arrive en production. Un déploiement manuel, c’est un déploiement oubliable, non reproductible, et risqué.
Ce qu’il faut faire : même basique, mettez en place un pipeline CI dès les premiers jours. Un simple enchaînement lint → tests → build → deploy sur GitLab CI, GitHub Actions ou Jenkins. C’est quelques heures de travail pour des mois de sérénité. Et c’est aussi un signal fort envoyé à l’équipe : on prend la qualité au sérieux.
Erreur n°8 : Vouloir tout documenter d’un coup
Face au manque de documentation, le réflexe est de vouloir tout écrire : architecture, flux métier, schéma de base de données, API, processus de déploiement…
C’est louable. C’est aussi un gouffre de temps qui produit des documents obsolètes avant même d’être terminés.
Ce qu’il faut faire : documentez au fil de l’eau, au moment où vous explorez. Vous venez de comprendre un flux métier complexe ? Notez-le dans un ADR (Architecture Decision Record) ou un README dédié. Vous venez de résoudre un bug piégeux ? Documentez la cause et la solution.
La meilleure documentation d’un projet legacy, ce n’est pas un pavé exhaustif : c’est un journal de bord vivant, écrit par ceux qui découvrent le code, pour ceux qui viendront après.
Erreur n°9 : Travailler seul dans son coin
Le projet legacy fait peur. Et la peur isole. On n’ose pas poser de questions « bêtes ». On n’ose pas dire qu’on ne comprend pas. On passe 3 jours sur un problème qu’un collègue aurait résolu en 20 minutes parce qu’il a vécu le même il y a 6 mois.
Sur un projet legacy plus que sur n’importe quel autre, le travail en silos est fatal.
Ce qu’il faut faire : instaurez des pratiques collaboratives dès que possible. Le pair programming sur les zones critiques du code est extraordinairement efficace. Les revues de code systématiques créent un partage de connaissance organique. Un canal Slack ou Teams dédié aux « découvertes legacy » où chacun partage ses trouvailles (bonnes ou mauvaises) peut devenir l’outil le plus précieux de l’équipe.
Erreur n°10 : Perdre de vue la valeur business
La dernière erreur, et peut-être la plus importante. On s’engouffre dans la technique — refactoring, tests, migration, CI/CD — et on oublie pourquoi on fait tout ça : délivrer de la valeur aux utilisateurs et au business.
Un code legacy modernisé qui ne permet pas de livrer plus vite, de réduire les incidents, ou de débloquer de nouvelles fonctionnalités… n’a aucun intérêt. La modernisation n’est pas une fin en soi. C’est un moyen au service du produit.
Ce qu’il faut faire : chaque action technique doit être reliée à un objectif business mesurable. « On ajoute des tests sur le tunnel de paiement » → pour réduire les incidents de 50%. « On migre ce module en Symfony 7 » → pour pouvoir développer la feature X demandée par le client Y. « On met en place la CI » → pour passer de 1 déploiement par mois à 2 par semaine.
Quand le business comprend le lien entre la modernisation technique et ses résultats, il devient votre allié — pas votre frein.
Le legacy n’est pas une fatalité, c’est un terrain de jeu
Si vous lisez cet article, c’est probablement parce que vous êtes confronté à un projet legacy — ou que vous allez l’être bientôt. Ce n’est pas une punition. C’est une des expériences les plus formatrices qu’un développeur puisse vivre.
Mais pour en tirer le meilleur, il faut y entrer avec la bonne posture : de l’humilité face au code existant, de la méthode dans la modernisation, et une vision claire de l’objectif business.
Les 10 erreurs de cet article se résument en une phrase : ne confondez pas urgence et précipitation.
Vous reprenez un projet legacy et vous ne savez pas par où commencer ?
Depuis plus de 13 ans, j’accompagne des entreprises pour auditer, stabiliser et moderniser leurs applications PHP legacy. Mon approche : comprendre avant d’agir, sécuriser avant de transformer, et toujours relier la technique au business.
👉 Prenez un RDV découverte gratuit et faisons le point ensemble sur votre situation.
Joan Drozo — Développeur PHP expérimenté, spécialiste de la modernisation d’applications legacy. +13 ans d’expérience. Basé à Rennes.