Nach einigen Typen wie dem Fahnder und dem Schmutzfink, die sich mehr oder weniger professionell mit Sourcecode auseinander gesetzt haben, diskutieren wir in dieser Folge ein anderes Problem bei der Wartung existierender Systeme: Man hat Ihnen viel Code übertragen, den Sie aufrechterhalten und weiterentwickeln müssen, zu dem aber keine geeignete Dokumentation vorhanden ist. So geht es Beate, die mit Ihrem Team gerade 840 000 Zeilen C++ geerbt hat – und die nächsten Wünsche der Kunden stehen schon an.

Verstehen ist schwierig, dokumentieren einfach

Für Nachdokumentation hat man Beate weder ein Budget noch die notwendige Zeit zugestanden. Alle drei Monate verlangen die Kunden und auch die Projektleitung ein neues Release. Beate weiß aber aus Erfahrung: Wenn man zehn Prozent des Programmcodes wegen Änderungen oder Erweiterungen anfassen muss, dann muss man mindestens 15 bis 20 Prozent verstanden haben – das, was man anpackt und ein bisschen darum herum. Und wenn ihr Team diese 15 bis 20 Prozent verstanden hat, ist es ein Leichtes, wenigstens diese Teile des Systems ordentlich nachzudokumentieren. Das macht vielleicht keinen Spaß, aber auch kaum Aufwand. Und es erspart allen anderen, die wieder an dieser Stelle des Codes vorbeikommen, den Reenginering-Aufwand. Wir nennen das unseren Delta-Ansatz für nachträgliche Architekturdoku oder die Politik der kleinen Schritte.

Wir kennen den Idealzustand

Wir wissen ja, wie Architekturdoku aussehen sollte, wenn sie vorhanden wäre. So, wie Sie wissen, wie ein schön geschmückter fertiger Christbaum am Heiligen Abend aussehen sollte. Wenn Sie aber keine Zeit und kein Geld haben und trotzdem die große rote Kugel möglichst schnell und an der richtigen Stelle des Christbaums anbringen wollen, was brauchen Sie dann? Nun ja, mindestens einen Christbaumständer, den Stamm, einen dicken Ast relativ nahe beim Boden, weil die Kugel ja groß ist. Und dann können Sie die Kugel schon genau dort hinhängen, wo sie auch am fertigen Christbaum hingehört. Der Rest des Baums sieht noch ziemlich kahl aus, aber dafür ist einfach keine Zeit. Aber mit jeder Kerze, jeder weiteren Kugel und jeder Schleife nähern wir uns dem Idealzustand.

Geduld

Was Beate mit dem ersten Release unter ihrer Verantwortung geschafft hat, ist nicht das Traumziel des Projekts, aber das, was machbar war. Jetzt braucht es nur ein bisschen Geduld: circa acht bis zwölf Releases, was bei vielen Produkten vielleicht einen Zeitraum von zwei bis drei Jahren bedeutet. In diesem Zeitraum kommt das Wartungsteam fast überall an den Sourcecode und kann mit der Delta-Technik langsam aber sicher eine gute Architekturdokumentation nachträglich schaffen.

In der Praxis geht es schneller

Theoretisch sind Sie nach acht bis zwölf Mal 15 Prozent nahe bei 100 gelandet. In der Praxis geht es meist schneller. Wenn Sie schon die große rote Kugel auf den unteren Ast hängen, dann kann man die Kerzen auf diesem Ast ja auch ausrichten und mit Schleifen versehen. Wir sind ohnehin gerade an dieser Stelle. Durch den Good Will aller Beteiligten passiert vielleicht bei jedem Release etwas mehr, als unbedingt sein muss, weil man sein Modellierungstool ohnehin gerade offen hat. Wir haben in der Praxis oft beobachtet, dass auch große Systeme ohne Zusatzaufwand in ein bis anderthalb Jahren bereits ausreichend nachdokumentiert waren. Voraussetzung ist nur ein bisschen Disziplin. Sie sollten sich wenigsten im Team auf ein gemeinsames Master-Repository oder ein zentrales Wiki einigen, damit nicht jeder einzelne – unauffindbar für die anderen – nur private Erkenntnisse festhält

Das größte Hindernis

Das störendste Element während dieser Delta-Arbeiten ist die Koexistenz der neuen Dokumentation mit anderen, veralteten Dokumenten. Solange die im Projekt – mangels Besserem – noch Gültigkeit haben, sind Sie immer wieder versucht, an diesen noch Nachbesserungen vorzunehmen, statt am zentralen, neuen Architekturdokument zu arbeiten. Unsere Empfehlung lautet daher: Sehen Sie zu, diese anderen Dokumente so schnell wie möglich überflüssig zu machen und zu vernichten. Kopieren Sie größere, unstrukturierte Teile einfach heraus und hängen Sie diese – unaufgeräumt wie sie sind – in das neue zentrale Repository an die richtige Stelle, wo sie im Idealfall stehen sollten. Sie markieren diese Teile jedoch als „noch nicht aufgeräumt“ (z. B. durch farbige Hinterlegung des ganzen Texts). Aber sie hängen jetzt bereits richtig. Der Nächste, der an der Stelle vorbeikommt, sieht die Warnung und kann wieder ein Stückchen mehr aufräumen. Das alte Dokument ist jedoch weg und stört nicht mehr.

Fazit

Ein altes Sprichwort besagt: Jede noch so lange Reise beginnt mit dem ersten Schritt. Mit kleinen Schritten kommt man auch nachträglich zu einer guten Architekturdokumentation, wenn man nur weiß, wie, und etwas Geduld mitbringt. Die meisten unserer Systeme leben sehr lange, oft länger als geplant und gewollt, und müssen einsatzfähig gehalten werden. Das Delta-Verfahren gibt Ihnen sukzessive brauchbare Architekturdokumentation und verbessert das Leben des Wartungsteams und von Projektneulingen erheblich. Lassen Sie sich Zeit. Folgen Sie dem Beispiel von Beate und dokumentieren Sie nur so viel, wie Sie ohnehin über das System im Zuge Ihrer normalen Arbeit verstehen müssen – das aber konsequent.

Aufmacherbild: Computer programing source code on blue electronics background von Shutterstock / Urheberrecht: Peter Gudella