Comment évaluer une refactorisation PHP avec des métriques de maintenabilité vérifiables

Une refactorisation peut réduire la duplication tout en compliquant les changements si elle ajoute des abstractions confuses ou déplace la complexité ailleurs. Pour évaluer son résultat, il ne suffit pas de comparer un score ni de vérifier que les tests passent : il faut définir ce que l’on souhaite améliorer, observer plusieurs signaux et vérifier si le système est plus facile à modifier.

Ce guide explique comment mesurer la maintenabilité d’une application PHP avant et après une refactorisation, sans transformer les métriques en objectifs isolés. La méthode s’applique à une classe, un module ou un flux métier, à condition de comparer le même périmètre et d’en consigner le contexte.

Pourquoi une métrique isolée ne prouve pas la maintenabilité

La maintenabilité est la capacité à comprendre, tester et modifier un système avec un niveau de risque raisonnable. Aucun indicateur ne représente à lui seul ces capacités. Un nombre de lignes inférieur ne signifie pas nécessairement une complexité moindre ; une couverture plus élevée ne garantit pas des tests utiles ; et un score statique favorable ne révèle pas si l’équipe comprend la conception.

En outre, les métriques peuvent évoluer pour des raisons étrangères à la refactorisation : mise à jour d’un outil, règles d’analyse différentes, changements de périmètre ou intégration de code généré dans le rapport. Un chiffre doit donc être interprété en tenant compte de sa méthode de calcul, de la zone analysée et des limites connues.

Il ne s’agit pas de prouver que le changement a « amélioré le code » dans l’absolu, mais de vérifier s’il a résolu un problème concret sans introduire de risques disproportionnés.

Définir la capacité de changement à améliorer

Avant de mesurer, formulez une hypothèse vérifiable et circonscrite. Par exemple : « Séparer les règles de calcul de cette classe devrait permettre de les tester sans démarrer le flux HTTP » ou « Réduire les dépendances de ce service devrait limiter les changements nécessaires pour ajouter une règle ». L’hypothèse définit un résultat attendu, sans prescrire une architecture à la mode.

Délimitez la zone et les opérations concernées : classes, endpoints, commandes, jobs ou règles métier. Notez également ce qui est exclu, comme une intégration externe ou une dette connue qui ne sera pas traitée. Sans ce périmètre, une comparaison risque de mêler l’effet de la refactorisation à celui d’autres changements.

Il est utile de traduire l’hypothèse en observations pratiques. La règle devrait-elle être plus facile à trouver ? Pourra-t-on la tester sans base de données réelle ? Le nombre de modules à modifier pour un changement courant va-t-il diminuer ? Choisissez quelques questions auxquelles l’équipe peut répondre à partir d’éléments concrets.

Établir un état de référence avant de modifier le code

Consignez l’état initial à partir d’une révision identifiable du dépôt, avec les mêmes outils et la même configuration que ceux utilisés ensuite. Pour une zone PHP, il peut être utile de combiner les signaux suivants :

• Complexité : repérez les méthodes longues, les branches conditionnelles et les endroits où les décisions s’accumulent. La complexité cyclomatique peut servir de repère, mais ne décrit pas à elle seule la difficulté à comprendre une règle.
• Couplage : identifiez les dépendances directes, les responsabilités mêlées et les liens avec l’infrastructure. Observez si une modification oblige à connaître ou à toucher des composants sans rapport.
• Duplication : localisez la logique répétée en distinguant la duplication accidentelle des règles similaires qui doivent évoluer séparément.
• Tests : consignez les comportements importants couverts, les tests fiables et les dépendances qui exigent des services externes pour exécuter un test.
• Exploitation et livraison : notez les incidents de production ou les régressions pertinents, les difficultés de déploiement du changement et les étapes manuelles associées, s’ils concernent la zone.

Si vous utilisez l’analyse statique, conservez le nom de l’outil, les règles, la version et la commande. Sans ces informations, le chiffre n’est pas reproductible. Séparez également le code généré ou externe lorsque la configuration le permet, et consignez les exclusions.

Choisir des indicateurs vérifiables et consigner leurs limites

Sélectionnez des indicateurs qui répondent à l’hypothèse. Pour une refactorisation visant à isoler la logique, on peut mesurer le nombre de dépendances nécessaires pour la tester, la présence de tests de comportement pertinents et le temps qu’il faut à une personne de l’équipe pour trouver le point à modifier. Pour réduire le couplage, on peut observer le nombre de composants à modifier dans le cadre d’une tâche représentative.

Ne transformez pas les durées ou les décomptes en vérités universelles : la taille de la tâche, l’expérience de la personne qui la réalise et les interruptions ont une influence. Si vous utilisez ces données, consignez ces conditions et considérez le résultat comme un signal, et non comme une comparaison de productivité entre personnes.

Documentez chaque indicateur en précisant quatre éléments : ce qu’il mesure, comment il est obtenu, quel résultat était attendu et ce qu’il ne peut pas prouver. Par exemple, un décompte des dépendances peut montrer une réduction, mais ne prouve pas que les nouvelles abstractions sont faciles à comprendre. La revue technique doit le vérifier.

Comparer avant et après avec la même méthode

Après la refactorisation, répétez l’analyse sur le même périmètre, avec la même configuration et, dans la mesure du possible, dans des conditions équivalentes. Distinguez les changements fonctionnels des changements structurels lors de la revue. Si les deux ont été effectués en même temps, déterminez à quels changements correspondent les éléments observés et évitez d’attribuer l’ensemble du résultat à la refactorisation.

En plus des métriques, testez un changement réel ou représentatif : corriger une règle, ajouter une condition métier ou adapter une intégration. Vérifiez quels fichiers ont dû être modifiés, quels tests ont été nécessaires et où des incertitudes sont apparues. Il n’est pas nécessaire de créer une tâche artificielle s’il existe déjà un travail comparable ; en revanche, il faut éviter de présenter une impression anecdotique comme un résultat concluant.

Une amélioration cohérente associe plusieurs signaux : par exemple, moins de dépendances pour tester une règle, des tests mieux ciblés et un parcours de modification que l’équipe peut expliquer. Si la complexité d’une méthode diminue, mais que la logique est davantage dispersée ou que le flux devient plus difficile à suivre, il faut réexaminer le bilan.

Combiner les mesures avec la revue et les retours de l’équipe

La revue technique doit vérifier si les responsabilités sont mieux définies, si les noms reflètent le domaine et si les nouvelles interfaces répondent à un besoin réel. Elle doit également rechercher les risques introduits : contrats dupliqués, inversion des dépendances source de confusion, changements accidentels de comportement ou nouvelle couche qui se contente de rediriger les appels.

Les retours de l’équipe apportent des éléments sur la compréhension et l’exploitation. Demandez s’il est plus facile de trouver la règle, d’écrire un test ou d’estimer la portée d’un changement. Associez les réponses à des exemples concrets et consignez les désaccords : une architecture peut être claire pour la personne qui l’a créée et opaque pour celle qui maintient le système.

En PHP, vérifiez également que la refactorisation respecte les contrats existants : types, exceptions, effets de bord, sérialisation et comportement observable des API. Une conception interne plus ordonnée ne compense pas une régression fonctionnelle ou une incompatibilité imprévue.

Erreurs fréquentes dans la mesure de la maintenabilité

• Courir après la couverture : augmenter le pourcentage peut ajouter des tests superficiels. Évaluez si les comportements et les cas à risque sont testés, et pas seulement si des lignes sont exécutées.
• Récompenser la réduction du nombre de lignes : compacter le code peut masquer des décisions et compliquer la revue des changements. La taille n’est pas une mesure directe de la clarté.
• Optimiser un score : adapter le code à un outil peut laisser intact le problème de conception. Cherchez à comprendre ce que signifie l’évolution du score et vérifiez son effet sur une tâche réelle.
• Comparer des périmètres différents : mêler de nouveaux fichiers, du code exclu ou des règles modifiées fausse l’interprétation. Gardez la méthode stable ou expliquez les différences.
• Ignorer le comportement : une refactorisation doit préserver le comportement attendu, sauf si le changement fonctionnel est défini et validé séparément.

Modèle succinct pour décider de la suite

À la fin de l’évaluation, consignez les éléments suivants :

• Zone et objectif : quelle partie a été refactorisée et quelle capacité de changement devait être améliorée.
• État de référence et méthode : révision du code, outils, configuration, périmètre et exclusions.
• Signaux observés : résultats avant et après, ainsi que les limites de chaque indicateur.
• Validation pratique : tests, revue technique et éléments issus d’un changement représentatif.
• Risques en suspens : comportement non couvert, dette reportée et effets opérationnels à vérifier.
• Décision : poursuivre si l’hypothèse est étayée et les risques acceptables ; ajuster si les signaux sont mitigés ou si un problème de compréhension subsiste ; arrêter si le coût ou le risque dépasse le bénéfice attendu.

La question finale n’est pas de savoir si le code obtient un meilleur score, mais si l’équipe peut modifier cette partie avec davantage de clarté et de maîtrise. Un état de référence reproductible, plusieurs signaux complémentaires et une revue honnête permettent de prendre cette décision sans confondre l’activité de refactorisation avec une amélioration démontrée.