Architekturen dokumentieren: Voll unagil?

Es ist Montag morgen, und ein neuer Mitarbeiter verstärkt das Projekt. Der Neue hat viele Fragen: „Was leistet das System überhaupt? Wie checke ich die Sourcen aus, und wie baue ich die Software? Was brauche ich für Tools? Aus welchen Bestandteilen besteht die Software? Wie arbeiten diese zusammen? Wenn ich neue Funktionalität hinzufügen soll – wie stelle ich das an? Hier ist doch schon was Ähnliches, kann ich das wiederverwenden? Wieso habt Ihr das denn so gemacht? …“

Solche Fragen zielen nicht nur auf Details, sondern auch auf Strukturen, auf Abhängigkeiten, auf getroffene Entscheidungen. Kurz: Auf Architektur. Wer beim Beantworten auf Hilfsmittel wie Entwürfe, Diagramme und Konzepte zurückgreifen kann, tut sich leichter. Und spätestens wenn in der Wartung keiner der ursprünglich Beteiligten mehr zum Antworten greifbar ist, ist Dokumentation unerlässlich.

Nun zählt Dokumentieren generell kaum zu den Lieblingsbeschäftigungen eines Java-Entwicklers. Für Quellcode-Dokumentation mit Javadoc reicht die Motivation häufig noch. Doch gerade Architektur und Entwurf einer Softwarelösung sind meiner Erfahrung nach in vielen Projekten gar nicht oder zumindest nicht angemessen dokumentiert. Bevor wir weitermachen – Was genau ist hier mit Softwarearchitektur gemeint? Ein kompakter Definitionsversuch beschreibt Architektur als die Gesamtstruktur der Lösung. Das ist sehr abstrakt und lässt zudem einige Aspekte außer Acht; aber ohnehin gibt es für den Begriff Softwarearchitektur keine allgemein akzeptierte Definition. Insbesondere eine Abgrenzung zum Entwurf ist in vielen Fällen schwierig und bringt in der Praxis auch nicht wirklich weiter (zu den Schwierigkeiten der Definition und zur Abgrenzung finden Sie z.B. bei G. Starke [1] Lesenswertes).

Aber was hilft in der Praxis? Beim Versuch, eine Softwarearchitektur zu dokumentieren, tun sich viele schwer, und die mühsam erstellen Ergebnisse überzeugen oft nicht. Wichtige Fragen, die sich der Leser stellt, werden nicht beantwortet. Oder die Dokumentation ist zwar umfangreich, aber (auch deshalb?) mit der Zeit veraltet. Sie gibt nicht den aktuellen Stand wieder und ist damit nutzlos geworden. Bei Reviews erhalte ich auf die Frage nach der Architekturdokumentation ab und an sogar eine Antwort wie diese: „Solche Arbeitsergebnisse haben wir hier im Projekt gar nicht; wir gehen agil vor. Der Quelltext ist die Dokumentation.“

Was sich bei näherem Hinsehen im Extremfall als „Wir gehen überhaupt nicht vor“ entpuppen kann, beinhaltet ein falsches Verständnis von Agilität. Denn das im Agilen Manifest [2] postulierte „Funktionierende Software vor umfassender Dokumentation“ ist ja gerade nicht so zu verstehen, dass Dokumentation unwichtig ist. Sie ist ganz im Gegenteil wertvoll, nur hat im Zweifelsfall das Funktionieren der Software eine höhere Priorität. Die spannende Frage ist daher, wie Dokumentation eingesetzt werden kann, um agile Prinzipien wie funktionierende Software oder Zusammenarbeit optimal zu unterstützen.

Aufwand und Nutzen müssen in angemessenem Verhältnis stehen, veraltete Dokumentation schadet oft mehr als sie nutzt. Gerade bei der Dokumentation mit Hilfe der UML wird mir in Seminaren oft von Erfahrungen berichtet, wo zu Beginn des Projektes ambitioniert Entwürfe dokumentiert wurden, die Modelle sich dann aber von der Realität (der Implementierung) entfernten, und dann nicht mehr nachgezogen wurden. Im Nachhinein wird den Aufwänden nachgetrauert, die in die initiale Erstellung geflossen sind. Dabei wird übersehen, dass die Diagramme oft von großem Nutzen waren, um die Lösung überhaupt zu entwerfen und anschließend im Team zu kommunizieren.

Und vielleicht hätten weniger detailverliebte, prägnantere Arbeitsergebnisse, ggf. mit einfacheren Werkzeugen erstellt, die gleiche Wirkung erzielt, und wären im weiteren Verlauf leichter aktuell zu halten gewesen. Der oben beschriebene negative Effekt des Auseinanderdriftens äußert sich insbesondere dann, wenn das UML-Modell eine ähnliche Detaillierung aufweist wie die Implementierung. Auf das richtige Abstraktionsniveau kommt es an.

Diese neue Kolumne soll Ihnen in den nächsten Monaten praktisch umsetzbare Anregungen liefern, wie Sie Architektur angemessen dokumentieren können. Welche Arbeitsergebnisse, Werkzeuge und Methoden haben sich in der Praxis bewährt, um Ideen zu kommunizieren? In diesem Zusammenhang werden verschiedene Aspekte von Softwarearchitektur beleuchtet. Erprobtes Vorgehen kommt ebenso vor wie konkrete Diagrammformen und auch ein bisschen UML. Doch wie sagte mein Kollege Tim Weilkiens einmal so schön: „Nur Kästchen zu zeichnen genügt nicht.“

Versetzen Sie sich beim Dokumentieren in Ihre Zielgruppe! Auftraggeber haben andere Interessen als Entwickler. Mein Lieblingsrollenwechsel für die Architekturdokumentation ist der (imaginäre) neue Mitarbeiter. Stellen Sie sich vor, Sie müssten ab nächster Woche Ihr Projekt unterstützen und hätten keine Ahnung. Welche Fragen würden Sie stellen?

Links & Literatur

[1] Gernot Starke, “Effektive Software-Architekturen”, Hanser Fachbuch, 5. Auflage 2011
[2] Manifesto for Agile Software Development, http://www.agilemanifesto.org

Zuerst erschienen hier:
Stefan Zörner: Kolumne Architekturen dokumentieren.
“Voll unagil”, Java Magazin, 10/2008, 1 Seite, S. 69
(mit freundlicher Genehmigung)