Legacy-Code dokumentieren: Warum und wie man nachträglich Dokumentation erstellt

Ihre Software läuft seit Jahren. Niemand hat je aufgeschrieben, wie sie funktioniert. Wer heute etwas ändern will, muss den Code erst verstehen, bevor er ihn anfassen kann. Das kostet Zeit, Nerven und Geld.

Legacy-Code dokumentieren klingt nach einem Projekt, das nie fertig wird. Mit dem richtigen Ansatz ist es aber machbar, auch mit begrenzten Ressourcen. Dieser Artikel zeigt, warum undokumentierter Code zum Risiko wird und wie Sie Schritt für Schritt Ordnung schaffen.

Warum undokumentierter Code zum Problem wird

Die meisten Legacy-Systeme sind ohne Dokumentation entstanden. Zeitdruck stand über Sorgfalt. Das war damals eine schnelle Lösung, heute eine offene Frage: Wer weiß eigentlich noch, wie das System wirklich funktioniert?

Ohne Dokumentation wiederholt sich immer dasselbe Muster. Ein neuer Entwickler übernimmt das System. Er liest sich tagelang durch Funktionen, deren Zweck sich ihm nicht erschließt. Kommentare fehlen oder sind veraltet. Variablennamen wie $tmp2 oder $data_neu geben keinen Hinweis auf ihren eigentlichen Zweck. Am Ende trifft der Entwickler Annahmen, die sich später als falsch herausstellen.

Ein typisches Beispiel: Eine Funktion berechnet einen Rabatt. Niemand weiß mehr, warum ein bestimmter Kunde von der Berechnung ausgenommen ist. War das eine bewusste Sonderregel? Oder ein Fehler, der sich eingeschlichen hat und seit Jahren mitläuft? Ohne Dokumentation lässt sich das nicht beantworten. Jede Änderung wird zum Risiko.

Welche Konsequenzen entstehen, wenn nichts passiert

Fehlende Dokumentation ist kein Schönheitsfehler. Sie hat konkrete Folgen für Ihren Betrieb.

Neue Entwickler brauchen deutlich länger für die Einarbeitung. Was mit Dokumentation in Tagen möglich wäre, dauert ohne sie Wochen. Kein Entwickler will Ihren alten Code anfassen, wenn er ihn erst mühsam entschlüsseln muss, bevor er überhaupt produktiv wird. Viele Dienstleister rechnen diesen Aufwand direkt in ihr Angebot ein, oder sie lehnen den Auftrag gleich ab.

Fehler häufen sich, wenn Zusammenhänge unbekannt sind. Eine Änderung an einer Stelle bricht eine andere Funktion, weil niemand wusste, dass beide zusammenhängen. Solche Fehler sind teuer, weil man sie oft erst in der Produktion bemerkt, wenn Kunden bereits betroffen sind.

Wissen geht verloren, wenn Mitarbeiter das Unternehmen verlassen. Was nur im Kopf einer Person existierte, ist nach der Kündigung weg. Dieses Risiko wächst mit jedem Jahr ohne Dokumentation. Manche Unternehmen merken das erst, wenn der einzige Entwickler, der das System kannte, bereits gekündigt hat.

Und schließlich: Entscheidungen werden schwerer. Ohne Dokumentation lässt sich kaum einschätzen, wie aufwendig eine Änderung wirklich ist. Angebote von externen Dienstleistern fallen entsprechend vorsichtig und teuer aus, weil niemand das Risiko genau kalkulieren kann.

Wie Sie Legacy-Code pragmatisch dokumentieren

Eine vollständige Dokumentation zu verlangen ist unrealistisch. Der bessere Weg: Prioritäten setzen und in kleinen Schritten vorgehen.

Schritt 1: Den Überblick zuerst

Fangen Sie nicht bei einzelnen Funktionen an. Zeichnen Sie zuerst die grobe Architektur auf. Welche Module gibt es? Wie kommunizieren sie miteinander? Welche externen Systeme sind angebunden, etwa Zahlungsdienstleister oder Versandanbieter? Ein einfaches Diagramm auf einer Seite reicht oft aus, um neuen Entwicklern die Orientierung zu geben. Perfektion ist hier nicht das Ziel, Orientierung schon.

Schritt 2: Kritische Pfade zuerst dokumentieren

Nicht jeder Teil des Systems ist gleich wichtig. Dokumentieren Sie zuerst, was den Kernbetrieb trägt: Zahlungsabwicklung, Login, Datenexport, die Prozesse, bei denen ein Ausfall sofort schmerzt. Randfunktionen, die selten genutzt werden, können warten.

Schritt 3: Wissen aus Köpfen extrahieren

Oft steckt das wichtigste Wissen nicht im Code, sondern im Kopf eines einzelnen Mitarbeiters. Führen Sie Gespräche und notieren Sie die Antworten, bevor dieses Wissen verloren geht. Fragen Sie gezielt nach Sonderfällen und Ausnahmen. Genau diese werden später am häufigsten vergessen. Eine Stunde Interview kann Wochen an späterer Recherche sparen.

Schritt 4: Werkzeuge nutzen, die den Aufwand senken

Moderne Werkzeuge unterstützen beim Code-Review und beim Erkennen von Mustern in unbekanntem Code, auch wenn sie menschliches Verständnis nicht ersetzen. Sie beschleunigen die erste Analyse, die sonst Tage dauert, und liefern einen ersten Entwurf, den ein Mensch prüft und ergänzt.

Schritt 5: Dokumentation zur Gewohnheit machen

Einmalige Dokumentation veraltet wieder, wenn niemand sie pflegt. Legen Sie fest, wer bei Änderungen die Dokumentation aktualisiert, und machen Sie das zum festen Bestandteil jeder Codeänderung. Kleine, regelmäßige Ergänzungen bringen langfristig mehr als ein einmaliges großes Projekt, das nach drei Monaten wieder veraltet ist.

Welches Format eignet sich für die Dokumentation?

Es muss kein aufwendiges Wiki sein. Für viele Legacy-Projekte reicht eine einfache README-Datei im Projektverzeichnis, ergänzt um ein Architekturdiagramm und eine kurze Liste bekannter Besonderheiten. Wichtig ist, dass die Dokumentation dort liegt, wo Entwickler ohnehin arbeiten, und nicht in einem separaten System, das niemand öffnet. Je niedriger die Hürde, desto eher wird sie gepflegt.

Wie lange dauert das, und was kostet es?

Das hängt stark vom Umfang des Systems ab. Ein überschaubares PHP-Projekt mit klarer Struktur lässt sich oft innerhalb von ein bis zwei Wochen so dokumentieren, dass ein neuer Entwickler damit arbeiten kann. Ein gewachsenes System aus mehreren Jahrzehnten, mit vielen Sonderfällen und ohne Ansprechpartner, braucht deutlich mehr Zeit.

Entscheidend ist, dass Sie nicht auf Vollständigkeit warten, bevor Sie anfangen. Schon eine grobe Architekturübersicht und eine Liste der fünf wichtigsten Sonderfälle bringen sofort Nutzen. Der Rest kann folgen, während das System weiterläuft und genutzt wird. So bleibt der Betrieb ungestört, und die Dokumentation wächst mit jedem Sprint ein Stück weiter.

Wenn Dokumentation nicht reicht

Manchmal zeigt sich beim Dokumentieren, dass der Code selbst kaum wartbar ist. Einzelne Funktionen sind über Jahre gewachsen, ohne klare Struktur. In diesem Fall lohnt sich eine systematische Refactoring-Strategie. Dokumentation und Codeverbesserung ergänzen sich, sie ersetzen sich nicht. Beides gemeinsam macht ein System langfristig beherrschbar.

Wer die nachträgliche Dokumentation nicht allein leisten kann oder will, kann sie auch extern beauftragen. Das lohnt sich besonders, wenn internes Wissen ohnehin knapp ist und schnell verloren gehen könnte, etwa vor einer Übergabe oder einem Personalwechsel.

Fazit: Dokumentation ist Vorsorge, kein Nice-to-have

Legacy-Code zu dokumentieren wirkt am Anfang wie eine riesige Aufgabe. In kleinen Schritten wird sie machbar. Wer mit dem Überblick anfängt, die kritischen Pfade zuerst festhält, Wissen aus Köpfen extrahiert und Dokumentation zur Gewohnheit macht, reduziert Risiko und spart später Zeit und Geld.

Sprechen Sie uns an. Das Erstgespräch ist kostenlos. Wir schauen uns Ihren Code an und sagen Ihnen, wo eine Dokumentation am meisten bringt.