Zum Inhalt springen

Deine PHP-Anwendung hat keine Dokumentation? So lässt sie sich trotzdem übernehmen

Niemand weiss mehr genau, wie deine Anwendung funktioniert. Jede kleine Änderung fühlt sich an wie ein Risiko, vielleicht hat ein Anbieter schon abgewinkt, und das Wissen scheint mit dem bisherigen Entwickler gegangen zu sein. «Es gibt keine Dokumentation» ist der häufigste Satz zu Beginn einer Übernahme, aber er stimmt selten ganz: Das Wissen steckt im Code, in der Versionshistorie, in der Datenbank, auf dem Server und in den Köpfen deiner Leute. In fünf Schritten wird daraus wieder eine Anwendung, die du im Griff hast.

Von Dimitri König3 Min. Lesezeit

Eine laufende Anwendung dokumentiert sich in gewisser Weise selbst. Die Aufgabe ist, dieses verstreute Wissen einzusammeln und aufzuschreiben.

Wo steckt das Wissen, wenn es keine Doku gibt?

  • Im Code: Routen, Controller, Modelle und Konfiguration zeigen, was die Anwendung tut.
  • In der Versionshistorie: Commit-Nachrichten und Änderungen erklären, warum etwas so gebaut wurde.
  • In der Datenbank: Tabellen, Beziehungen und Datenmengen zeigen, was wirklich genutzt wird.
  • Auf dem Server: Cronjobs, Webserver-Konfiguration, Umgebungsvariablen und Logs zeigen, was im Hintergrund läuft.
  • Bei deinen Leuten: Wer täglich mit der Anwendung arbeitet, kennt die Abläufe, Sonderfälle und bekannten Macken.

Wie viel sich aus einem laufenden System zurückholen lässt, zeigt ein Projekt, bei dem das alte CMS weder eine API noch direkten Datenbankzugriff bot. Ein eigens entwickelter Scraper hat die ganze Website mit Tausenden Seiten erfasst, samt Hierarchie, Medien und Übersetzungen, und sie vollautomatisch nach TYPO3 übertragen: automatisierte CMS-Migration zu TYPO3.

In fünf Schritten zur beherrschbaren Anwendung

  1. Inventar erstellen. PHP-Version, Framework und Version, Abhängigkeiten laut composer.json und composer.lock, Datenbank, Server, externe Dienste. Das Ergebnis ist eine Liste, die dir zeigt, womit du es zu tun hast.
  2. Lauffähige Kopie aufsetzen. Die Anwendung läuft in einer Testumgebung mit derselben PHP-Version wie produktiv. Personendaten sind dort anonymisiert, damit die Testumgebung auch im Sinne des Datenschutzgesetzes unkritisch bleibt.
  3. Einstiegspunkte und Datenflüsse erfassen. Welche Seiten und Schnittstellen gibt es, welche Cronjobs und Queues laufen, welche Daten fliessen woher und wohin?
  4. Kritische Abläufe mit Tests absichern. Charakterisierungstests halten fest, wie sich Bestellung, Login oder Datenimport heute verhalten. Ab dann fällt jede ungewollte Änderung sofort auf.
  5. Dokumentation mitwachsen lassen. Alles, was die ersten vier Schritte zutage fördern, landet im Repository. So entsteht die Dokumentation nicht als Extraprojekt, sondern als Nebenprodukt der Arbeit.

Welche Dokumentation braucht eine übernommene Anwendung?

Dokument Inhalt Für wen
README Aufsetzen, lokal starten, wichtigste Befehle Jede Person, die am Code arbeitet
Betriebshandbuch Deployment, Backups, Cronjobs, Monitoring, Notfallablauf Betrieb und Support
Schnittstellenübersicht Externe Dienste, Datenflüsse, Zugänge (ohne Passwörter) Entwicklung und Fachabteilung
Architekturübersicht Aufbau, wichtigste Komponenten, bekannte Schwachstellen Entwicklung und Entscheider
Entscheidungsprotokoll Warum etwas so gebaut oder geändert wurde Alle, die später Entscheidungen treffen

Das Entscheidungsprotokoll folgt der Idee der Architecture Decision Records von Michael Nygard: kurze, datierte Einträge, die festhalten, welche Entscheidung warum getroffen wurde.

Wie verhinderst du, dass es wieder so weit kommt?

Das eigentliche Problem einer undokumentierten Anwendung ist nicht die fehlende Doku, sondern die Abhängigkeit von einer einzigen Person. Deshalb liegen Code und Dokumentation nach der Übernahme in einem Repository, auf das du jederzeit Zugriff hast, und alle Zugangsdaten in einem gemeinsamen Passwort-Tresor. So kann jederzeit auch jemand anderes übernehmen, auch ohne mich. Mit der laufenden Wartung wächst die Dokumentation bei jeder Änderung mit, statt wieder zu veralten. Wie der Einstieg aussieht, zeigt die Seite Webapplikation übernehmen. Worauf es bei einem halbfertigen Projekt oder KI-generiertem Code zusätzlich ankommt, steht im Artikel halbfertiges Projekt übernehmen.

Quellen

  1. [1]Characterization test · Wikipedia
  2. [2]Documenting Architecture Decisions · Michael Nygard, Cognitect, 2011
  3. [3]Bus-Faktor · Wikipedia
  4. [4]Bundesgesetz über den Datenschutz (DSG) · Fedlex, Schweizerische Eidgenossenschaft

Häufige Fragen.

Wie lange dauert es, eine undokumentierte Anwendung zu verstehen?

Das hängt von Grösse und Zustand ab. Die Grundlage, also Inventar, Risiken, Betrieb und Sofortmassnahmen, hast du mit dem Übernahme-Assessment innert fünf Arbeitstagen ab vollständigem Zugang. Das Detailwissen wächst danach mit jeder Aufgabe weiter und wird laufend dokumentiert.

Übernahme-Assessment

Brauchen wir den bisherigen Entwickler dafür?

Nein. Eine Übergabe hilft, weil sie Fragen schneller beantwortet, ist aber keine Voraussetzung. Code, Versionshistorie, Datenbank und Serverkonfiguration enthalten fast alles, was es zu wissen gibt. Was fehlt, klärt ein Gespräch mit deinen Leuten, die täglich mit der Anwendung arbeiten.

Wenn der Entwickler nicht erreichbar ist

Was ist ein Charakterisierungstest?

Ein Test, der festhält, wie sich eine Anwendung heute tatsächlich verhält, statt wie sie sich verhalten sollte. Der Begriff stammt von Michael Feathers. Solche Tests sind die Sicherheitsleine für Änderungen an Code, den niemand vollständig versteht, weil sie jede unbeabsichtigte Verhaltensänderung sofort sichtbar machen.

Welche Dokumentation ist das Minimum?

Eine Anleitung, wie die Anwendung lokal und auf dem Server läuft, ein Betriebshandbuch mit Deployment, Backups und Cronjobs, eine Übersicht der Schnittstellen und eine kurze Architekturbeschreibung. Alles im Repository, damit es mit dem Code aktuell bleibt.