Softwarearchitekturen dokumentieren und kommunizieren

Folge 5: Laufzeitsicht: Der jüngste Spieler fängt an!

Logo Kolumne
Brettspiele zu entwickeln ist mit der Softwareentwicklung durchaus vergleichbar. Auch hier wird konzipiert, entworfen und getestet. Und dokumentiert! Ein Teil der Dokumentation liegt am Ende jeder Spielepackung bei: Die Anleitung. Bei komplexen Spielen kann sie sehr umfangreich sein. Die Autoren müssen sich Gedanken machen, wie man Spielidee, -regeln und vielleicht sogar Hinweise zur Taktik effektiv kommuniziert. Gut gemachte Spielanleitungen haben eine klare Struktur mit oftmals gleichem Aufbau. Den Anfang macht stets die Darstellung des Spielzieles. Ähnlich wie bei der Architekturdokumentation verwenden Spielanleitungen im Anschluss verschiedene Sichten, um unterschiedliche Aspekte zu zeigen. Kapitel wie Spielmaterial und -vorbereitung zielen eher auf statische Aspekte ab. Den weitaus größten Teil einer Anleitung nimmt aber gewöhnlich der Spielablauf – Phasen, gültige Züge – also die Dynamik ein.
Abb. 1: Spielregeln für Springer beim Schach
Abb. 1: Spielregeln für Springer beim Schach
Bei den unterschiedlichen Sichten auf Softwarearchitektur finden sich dynamische Aspekte in der sogenannten Laufzeitsicht (alternativ: Verhaltenssicht). Hier geht es darum zu beschreiben, wie Softwareelemente zur Laufzeit interagieren, bzw. wie ein Element selbst sich verhält. Verglichen mit der Bausteinsicht [1] nimmt sie in Architekturdokumentation oftmals weniger Platz ein. In vielen Situationen macht jedoch erst die Zusammenschau aus Baustein- und Laufzeitsicht klar, wie das System eigentlich funktioniert, bzw. zu verwenden oder zu erweitern ist.

Wie gehen Sie als Architekt nun an die Dokumentation dynamischer Aspekte Ihres Softwaresystems heran? Klären Sie für jede konkrete Beschreibung von Laufzeitverhalten zunächst wichtige Fragen zum „was“ und „wie“! Zunächst: Was beschreiben Sie? Das Verhalten eines einzelnen Bausteins, oder das Zusammenspiels von mehreren? Einen speziellen Ablauf exemplarisch, oder die Menge aller möglichen Abläufe? Und im Anschluss: Wie beschreiben Sie es? Textuell, oder mit Hilfe einer oder mehrerer Abbildungen?
Abb. 2: Spielregeln für Bundles im OSGi-Framework
Abb. 2: Spielregeln für Bundles im OSGi-Framework
Gerade bei Abläufen, die Alternativen oder Ausnahmen beinhalten, bieten sich Visualisierungen an. Spielanleitungen machen es vor. Selbst die sonst eher drögen offiziellen Schachregeln [2] greifen zu Abbildungen, um z.B. die möglichen Bewegungen der Figuren zu erklären (siehe Abb. 1). In der Softwareentwicklung zählen Struktogramme zu den klassischen Techniken, um Verhalten zu beschreiben. Die UML 2 kennt unter anderem Aktivitäts-, Sequenz- und Zustandsdiagramme. Als ein Beispiel für letztere visualisiert Abbildung 2 die gültigen Zustände und Zustandsübergänge im Lebenszyklus eines OSGi-Bundles. Sie ist der OSGi-Spezifikation entnommen; eine gleichwertige textuelle Beschreibung wäre offensichtlich nicht so kompakt und würde sich dem Leser auch nicht so schnell erschließen.

Trotz der Vorzüge finden sich nicht in jeder Dokumentation Abbildungen zum Verhalten. Die Servletspezifikation z.B. beinhaltet keine einzige; die dynamischen Aspekte der Elemente werden ausschließlich textuell beschrieben. Das betrifft zum Beispiel die Reihenfolge, in der ein Servlet-Container die Lebenszyklusmethoden von Komponenten aufruft. In Anbetracht der geringen Komplexität der Sachverhalte mag diese Entscheidung bewusst getroffen worden sein.

Für Ihr eigenes Softwaresystem entscheiden Sie selbst, welche dynamischen Aspekte Sie wann und wie dokumentieren wollen. Auch den  Pflegeaufwand während der Entwicklung sollten Sie im Auge behalten.

Die Beschreibung dynamischer Aspekte im Rahmen der Dokumentation ist von besonders großer Bedeutung, wenn Ihr Softwaresystem gewollte Erweiterungspunkte aufweist. Wer ein neues Modul hinzufügt muss wissen, nach welchen Spielregeln das zu erfolgen hat. Das schließt neben statischen Belangen (z.B. geforderte Schnittstellen in Form von zu implementierenden Interfaces) auch dynamische ein. Wenn die Entwicklung von Erweiterungen forciert werden soll (z.B. in Plugin-Architekturen) tun Sie gut daran, hier ein besonderes Augenmerk drauf zu legen, vielleicht sogar Beispielimplementierungen in der Dokumentation zu besprechen.

Schach hat nicht den Anspruch, besonders gut erweiterbar zu sein. Man kann keine Zusatzfiguren kaufen. Viele moderne Autorenspiele hingegen bieten Ergänzungen an. Von modernen Softwareentwürfen erwartet man Erweiterbarkeit in der Regel sogar.

Links & Literatur

[1] S. Zörner: „Was ist was? Band 127: Unser Softwaresystem“, Java Magazin 1.2009
[2] Die FIDE-Schachregeln, Offizielle Übersetzung des DSB, http://www.schachbund.de
JavaMagazin 02.2009
Zuerst erschienen hier:
Stefan Zörner: Kolumne Architekturen dokumentieren.
"Laufzeitsicht: Der jüngste Spieler fängt an!", Java Magazin, 02/2009, 1 Seite, S. 57
(mit freundlicher Genehmigung)