Softwarearchitekturen dokumentieren und kommunizieren

Folge 7: Historisch gewachsen? - Entscheidungen festhalten

Logo Kolumne
1815 – Europa in Aufregung. Napoleon erlebt bei Waterloo ebendieses – er verliert seine letzte Schlacht. Mittlerweile haben Historiker reichlich Papier veröffentlicht, um die Gefechtsgeschehnisse zu dokumentieren und zu bewerten. Sie sind sich nicht in allen Punkten einig. Die Entscheidungen des Kaisers der Franzosen sind zwar in Form seiner Befehle überliefert, nicht immer ist aber klar, welche Alternativen er zuvor gegeneinander abgewogen hat, und warum er sich für eine bestimmte Option entschied. In einzelnen Punkten vermuten Geschichtsschreiber Fehler in Napoleons Handeln entdeckt zu haben. Sie können aber nur spekulieren, ob er sie aus Unwissenheit beging, oder ob eine Absicht dahinter stand, die sie nicht kennen.

Entscheidungen zu treffen ist die zentrale Aufgabe im Softwareentwurf. Es gibt zwar keine allgemein anerkannte Definition des Architekturbegriffs, aber eine sehr prominente [1] charakterisiert Softwarearchitektur als „Summe signifikanter Entscheidungen […]“. Architekturentscheidungen, also solche, die im weiteren Verlauf nur schwer zurückzunehmen sind, geben den Rahmen für die Lösung vor. Sie sind ein zentrales Arbeitsergebnis – Architektur erfolgreich umzusetzen heißt vor allem, sie im Team zu kommunizieren. Darüber hinaus sollten Sie Architekturentscheidungen geeignet dokumentieren.

Warum eigentlich? Damit spätere Geschichtsschreiber Ihr Projekt leichter erforschen können? So lange brauchen Sie in der Regel nicht warten. Schon der erste neue Mitarbeiter im Team wird viele Fragen stellen, die auf zentrale Entscheidungen abzielen. „Warum habt Ihr das denn mit X-Framework gemacht? Y-Framework ist doch viel besser!“ Nicht jeder im Team wird sich vielleicht noch erinnern können, was damals für X-Framework sprach. Gerade in wachsenden Projekten, die häufig neue Mitarbeiter integrieren,  kommt es zu den immer wieder gleichen Debatten, die leicht vermieden oder zumindest abgekürzt werden können. Neben der Wissensvermittlung und –erhaltung im Team sind dokumentierte Entscheidungen auch für Architekturbewertungen und Reviewes unerlässlich.
Abb. 1: Mögliche Struktur einer Architekturentscheidung
Abb. 1: Mögliche Struktur einer Architekturentscheidung
Was genau sollte festgehalten werden? Und in welcher Form? In der Praxis haben sich einfache Templates bewährt, die für jede relevante Entscheidung die gleichen Dinge abfragen. Abbildung 1 zeigt eine Mindmap mit Fragen, die Sie bei einer konkreten Architekturentscheidung, etwa in einem Workshop,  leiten und unterstützen können. Die nummerierten Hauptäste eignen sich als Kapitelüberschriften einer Vorlage. Wichtig ist neben der Darstellung der Fragestellung auch, warum die Sache relevant genug ist, um sie in den Rang einer Architekturentscheidung zu erheben. Stets enthalten sein sollte natürlich die Entscheidung selbst und die Information, wann sie mit welcher Begründung getroffen wurde.

Das „wann“ wird ab und an vergessen, dabei ist es sehr wichtig. Denn zum einen macht es Sinn, Entscheidungen in ihrer chronologischen Abfolge zu betrachten. Oft beeinflusst die Wahl einer Alternative die möglichen Optionen nachfolgender Entscheidungen. Wenn sich z.B. für die Bevorzugung standardisierter APIs in einer Java-Architektur entschieden wurde, macht es später wenig Sinn, proprietäre Persistenzframeworks in die engere Wahl zu ziehen. Auch in anderen Situationen erklärt der Zeitpunkt der Entscheidung, warum bestimmte Optionen überhaupt nicht in Betracht gezogen wurden, auch wenn sie scheinbar besser passen. Vielleicht gab es Y-Framework zum Zeitpunkt der Entscheidung noch gar nicht.

Architekturentscheidungen haben in der Regel weitreichende Auswirkungen auf die Entwicklung. Jeder im Team sollte sie kennen. Ein verlässlicher Ablageort ist ein geeignet aufgesetztes Projekt-Wiki, das auch der Lebendigkeit des Architekturprozesses Rechnung tragen kann. Architekturentscheidungen als großes Worddokument in den Niederungen eines nicht teamfähigen Netzwerklaufwerkes versteckt verliert man hingegen leicht aus den Augen.

2009 – Ein Softwaresystem in der Entwicklung. Es entsteht heute in der Regel iterativ; anders als Napoleon auf dem Schlachtfeld von Waterloo kann ein Entwicklungsteam heute oft noch lernen, und Dinge revidieren. Es ist nicht angebracht, Architekturdokumentation wie Geschichtsschreibung zu betreiben. Wenn zentrale Entscheidungen zu spät dokumentiert werden, ist der Findungsprozess und die Intention dahinter bereits in Vergessenheit geraten. Sollte zu einem späteren Zeitpunkt eine Entscheidung neu bewertet und ggf. geändert werden müssen, fehlen wichtige Informationen.
 
Werden wichtige Entscheidungen überhaupt nicht dokumentiert, können Sie später bei Fragen neuer Mitarbeiter oder im Architekturreview unter Umständen nur noch antworten mit „das ist historisch gewachsen“.
 

Links & Literatur

[1] P. Kruchten, "The Rational Unified Process: An Introduction", Addison-Wesley, 3. Aufl. 2004
JavaMagazin 04.2009
Zuerst erschienen hier:
Stefan Zörner: Kolumne Architekturen dokumentieren.
"Historisch gewachsen? - Entscheidungen festhalten", Java Magazin, 04/2009, 2 Seiten, S. 54
(mit freundlicher Genehmigung)