Wie Sie ein PHP-Refactoring anhand überprüfbarer Wartbarkeitsmetriken bewerten

Ein Refactoring kann Duplikate reduzieren und Änderungen dennoch erschweren, wenn es unverständliche Abstraktionen hinzufügt oder die Komplexität an eine andere Stelle verlagert. Um das Ergebnis zu bewerten, reicht es nicht, einen Wert zu vergleichen oder nur zu prüfen, ob die Tests bestehen: Sie müssen festlegen, was verbessert werden soll, mehrere Indikatoren beobachten und überprüfen, ob sich das System leichter ändern lässt.

Dieser Leitfaden erläutert, wie Sie die Wartbarkeit einer PHP-Anwendung vor und nach einem Refactoring messen, ohne Metriken zu isolierten Zielen zu machen. Die Methode eignet sich für eine Klasse, ein Modul oder einen Geschäftsprozess, sofern derselbe Umfang verglichen und der Kontext dokumentiert wird.

Warum eine einzelne Metrik die Wartbarkeit nicht belegt

Wartbarkeit ist die Fähigkeit, ein System mit vertretbarem Risiko zu verstehen, zu testen und zu ändern. Kein einzelner Indikator bildet diese Fähigkeiten vollständig ab. Weniger Zeilen bedeuten nicht unbedingt weniger Komplexität; eine höhere Testabdeckung garantiert keine nützlichen Tests; und ein günstiger statischer Analysewert zeigt nicht, ob das Team das Design versteht.

Außerdem können sich Metriken aus Gründen ändern, die nichts mit dem Refactoring zu tun haben: ein aktualisiertes Tool, andere Analyseregeln, Änderungen am Umfang oder generierter Code, der in den Bericht aufgenommen wird. Deshalb muss ein Wert zusammen mit seiner Berechnungsmethode, dem analysierten Bereich und den bekannten Einschränkungen interpretiert werden.

Es geht nicht darum, abstrakt zu beweisen, dass die Änderung „den Code verbessert“ hat. Es soll geprüft werden, ob sie ein konkretes Problem gelöst hat, ohne unverhältnismäßige Risiken einzuführen.

Festlegen, welche Änderbarkeit verbessert werden soll

Formulieren Sie vor der Messung eine überprüfbare und klar eingegrenzte Hypothese. Zum Beispiel: „Wenn die Berechnungsregeln aus dieser Klasse herausgelöst werden, sollten sie sich testen lassen, ohne den HTTP-Ablauf zu starten“ oder „Wenn die Abhängigkeiten dieses Dienstes reduziert werden, sollten für das Hinzufügen einer Regel weniger Änderungen nötig sein“. Die Hypothese benennt ein erwartetes Ergebnis und schreibt keine Architektur aus modischen Gründen vor.

Grenzen Sie den Bereich und die betroffenen Vorgänge ab: Klassen, Endpoints, Befehle, Jobs oder Geschäftsregeln. Notieren Sie auch, was außen vor bleibt, etwa eine externe Integration oder bekannte technische Schulden, die nicht angegangen werden. Ohne diese Abgrenzung kann ein Vergleich die Auswirkungen des Refactorings mit anderen Änderungen vermischen.

Es empfiehlt sich, die Hypothese in praktische Beobachtungen zu übersetzen. Sollte sich die Regel leichter finden lassen? Wird sie sich ohne echte Datenbank testen lassen? Sinkt die Zahl der Module, die für eine typische Änderung angepasst werden müssen? Wählen Sie wenige Fragen aus, die das Team anhand von Belegen beantworten kann.

Vor der Codeänderung eine Ausgangsbasis erfassen

Dokumentieren Sie den Ausgangszustand anhand eines eindeutig identifizierbaren Repository-Stands und mit denselben Tools und derselben Konfiguration, die Sie anschließend verwenden. Für einen PHP-Bereich kann die Kombination folgender Indikatoren sinnvoll sein:

• Komplexität: Prüfen Sie umfangreiche Methoden, bedingte Verzweigungen und Stellen, an denen sich Entscheidungen häufen. Die zyklomatische Komplexität kann Hinweise geben, beschreibt aber für sich genommen nicht, wie schwierig eine Regel zu verstehen ist.
• Kopplung: Erfassen Sie direkte Abhängigkeiten, vermischte Zuständigkeiten und Verbindungen zur Infrastruktur. Beobachten Sie, ob eine Änderung dazu zwingt, nicht zusammenhängende Komponenten zu kennen oder anzupassen.
• Duplikate: Finden Sie wiederholte Logik und unterscheiden Sie zufällige Duplikate von ähnlichen Regeln, die sich unabhängig voneinander weiterentwickeln sollen.
• Tests: Dokumentieren Sie, welche wichtigen Verhaltensweisen abgedeckt sind, welche Tests zuverlässig sind und welche Abhängigkeiten einen Test von externen Diensten abhängig machen.
• Betrieb und Auslieferung: Notieren Sie relevante Produktionsfehler oder Regressionen, den Aufwand für das Deployment der Änderung und die damit verbundenen manuellen Schritte, sofern sie für den Bereich relevant sind.

Wenn Sie statische Analysen verwenden, halten Sie den Namen des Tools, die Regeln, die Version und den Befehl fest. Eine Zahl ohne diese Angaben ist nicht reproduzierbar. Trennen Sie außerdem generierten oder externen Code, sofern die Konfiguration dies zulässt, und dokumentieren Sie die Ausschlüsse.

Überprüfbare Indikatoren auswählen und ihre Grenzen dokumentieren

Wählen Sie Indikatoren, die sich auf die Hypothese beziehen. Bei einem Refactoring, das Logik isolieren soll, könnten die Zahl der Abhängigkeiten, die für Tests erforderlich sind, das Vorhandensein relevanter Verhaltenstests und die Zeit, die ein Teammitglied zum Auffinden der Änderungsstelle benötigt, hilfreich sein. Zur Verringerung der Kopplung lässt sich beispielsweise beobachten, wie viele Komponenten bei einer repräsentativen Aufgabe geändert werden müssen.

Machen Sie aus Zeitangaben oder Zählwerten keine allgemeingültigen Wahrheiten: Der Umfang der Aufgabe, die Erfahrung der ausführenden Person und Unterbrechungen spielen eine Rolle. Wenn Sie solche Werte verwenden, dokumentieren Sie die Bedingungen und behandeln Sie das Ergebnis als Indikator, nicht als Produktivitätsvergleich zwischen Personen.

Dokumentieren Sie für jeden Indikator vier Angaben: was er misst, wie er ermittelt wird, welches Ergebnis erwartet wurde und was er nicht belegen kann. Eine Zahl zu Abhängigkeiten kann beispielsweise einen Rückgang zeigen, beweist aber nicht, dass die neuen Abstraktionen leicht verständlich sind. Das muss die technische Überprüfung klären.

Vorher und nachher mit derselben Methode vergleichen

Wiederholen Sie die Analyse nach dem Refactoring für denselben Umfang und mit derselben Konfiguration, möglichst unter vergleichbaren Bedingungen. Trennen Sie funktionale und strukturelle Änderungen bei der Überprüfung. Wenn beides gleichzeitig geändert wurde, ordnen Sie die jeweiligen Belege zu und vermeiden Sie, das gesamte Ergebnis dem Refactoring zuzuschreiben.

Testen Sie zusätzlich zu den Metriken eine reale oder repräsentative Änderung: eine Regel korrigieren, eine Geschäftsbedingung hinzufügen oder eine Integration anpassen. Prüfen Sie, welche Dateien geändert werden mussten, welche Tests erforderlich waren und wo Fragen aufkamen. Sie müssen keine künstliche Aufgabe erstellen, wenn es bereits vergleichbare Arbeit gibt; Sie sollten jedoch vermeiden, einen anekdotischen Eindruck als schlüssiges Ergebnis darzustellen.

Eine konsistente Verbesserung zeigt sich in mehreren Indikatoren: zum Beispiel weniger Abhängigkeiten beim Testen einer Regel, gezieltere Tests und ein Änderungsweg, den das Team erklären kann. Sinkt die Komplexität einer Methode, während sich die Logik stärker verteilt oder der Ablauf schwerer nachvollziehen lässt, muss die Gesamtbilanz überprüft werden.

Messungen mit Überprüfung und Teamfeedback kombinieren

Bei der technischen Überprüfung sollte gefragt werden, ob die Zuständigkeiten klarer sind, die Bezeichnungen die Fachlichkeit widerspiegeln und die neuen Schnittstellen einen tatsächlichen Bedarf erfüllen. Ebenso sollten neu entstandene Risiken gesucht werden: doppelte Verträge, verwirrend umgekehrte Abhängigkeiten, versehentliche Verhaltensänderungen oder eine neue Schicht, die Aufrufe lediglich weiterleitet.

Das Teamfeedback liefert Hinweise zum Verständnis und zum Betrieb. Fragen Sie, ob sich die Regel leichter finden, ein Test leichter schreiben oder der Umfang einer Änderung leichter einschätzen lässt. Verknüpfen Sie die Antworten mit konkreten Beispielen und dokumentieren Sie Meinungsverschiedenheiten: Eine Architektur kann für die Person, die sie erstellt hat, klar und für die Person, die das System wartet, undurchsichtig sein.

Prüfen Sie bei PHP außerdem, ob das Refactoring bestehende Verträge einhält: Typen, Ausnahmen, Seiteneffekte, Serialisierung und beobachtbares Verhalten der APIs. Ein intern aufgeräumteres Design gleicht keine funktionale Regression und keine unerwartete Inkompatibilität aus.

Häufige Fehler bei der Messung der Wartbarkeit

• Testabdeckung um ihrer selbst willen erhöhen: Ein höherer Prozentsatz kann oberflächliche Tests hervorbringen. Bewerten Sie, ob Verhaltensweisen und Risikofälle getestet werden, nicht nur, ob Zeilen ausgeführt werden.
• Weniger Zeilen belohnen: Kompakterer Code kann Entscheidungen verschleiern und die Überprüfung von Änderungen erschweren. Die Größe ist kein direktes Maß für Verständlichkeit.
• Einen Wert optimieren: Wird der Code an ein Tool angepasst, kann das eigentliche Designproblem bestehen bleiben. Prüfen Sie, was die Änderung bedeutet, und bestätigen Sie ihre Wirkung anhand einer realen Aufgabe.
• Unterschiedliche Umfänge vergleichen: Werden neue Dateien, ausgeschlossener Code oder geänderte Regeln vermischt, ist die Auswertung nicht aussagekräftig. Halten Sie die Methode konstant oder erläutern Sie die Unterschiede.
• Das Verhalten ignorieren: Ein Refactoring sollte das erwartete Verhalten bewahren, sofern die funktionale Änderung nicht separat definiert und validiert wurde.

Kurze Vorlage für die Entscheidung über das weitere Vorgehen

Halten Sie zum Abschluss der Bewertung Folgendes fest:

• Bereich und Ziel: Welcher Teil refaktoriert wurde und welche Änderbarkeit verbessert werden sollte.
• Ausgangsbasis und Methode: Code-Revision, Tools, Konfiguration, Umfang und Ausschlüsse.
• Beobachtete Indikatoren: Ergebnisse vor und nach der Änderung sowie die Grenzen jedes Indikators.
• Praktische Validierung: Tests, technische Überprüfung und Belege anhand einer repräsentativen Änderung.
• Offene Risiken: Nicht abgedecktes Verhalten, aufgeschobene technische Schulden und noch zu prüfende betriebliche Auswirkungen.
• Entscheidung: Fortfahren, wenn die Hypothese Bestand hat und die Risiken vertretbar sind; anpassen, wenn die Indikatoren gemischt sind oder Verständnisprobleme bestehen; stoppen, wenn Aufwand oder Risiko den erwarteten Nutzen übersteigen.

Die abschließende Frage lautet nicht, ob der Code einen besseren Wert erzielt, sondern ob das Team diesen Bereich klarer und kontrollierter ändern kann. Eine reproduzierbare Ausgangsbasis, mehrere sich ergänzende Indikatoren und eine ehrliche Überprüfung ermöglichen diese Entscheidung, ohne Refactoring-Aktivität mit nachgewiesener Verbesserung zu verwechseln.