Es ist Montagmorgen, 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 Quellcodedokumentation 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 führt in der Praxis auch nicht wirklich weiter (zu den Schwierigkeiten der Definition und zur Abgrenzung finden Sie z.B. bei Gernot Starke [Starke: Effektive Software-Architekturen, Hanser Fachbuch, 3. Aufl., 2007] 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 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 mithilfe der UML wird mir in Seminaren oft von Erfahrungen berichtet, dass zu Beginn des Projekts 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, gegebenenfalls 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?
Stefan Zörner ist Anwendungsarchitekt, Berater, Trainer und Coach bei der oose Innovative Informatik GmbH in Hamburg. Er arbeitet dort im Bereich Software-Engineering, ist Autor zweier Bücher und zahlreicher Fachartikel rund um Java, u.a. im Java Magazin und bei IBM developerWorks. Darüber hinaus ist er seit 2005 Committer im Directory Project der Apache Software Foundation.
