Leseprobe

Stefan Zörner

Softwarearchitekturen dokumentieren und kommunizieren

Entwürfe, Entscheidungen und Lösungen nachvollziehbar undwirkungsvoll festhalten

ISBN (Buch): 978-3-446-44348-8

ISBN (E-Book): 978-3-446-44442-3

Weitere Informationen oder Bestellungen unter

http://www.hanser-fachbuch.de/978-3-446-44348-8

sowie im Buchhandel.

© Carl Hanser Verlag, München

Inhalt

Geleitwort zur 1. Auflage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XI

Überblick: Dokumentationsmittel im Buch. . . . . . . . . . . . . . . . . . . . . . . . . XIII

1 Warum Software architekturen dokumentieren? . . . . . . . . . . . . . . . . . .11.1 Montagmorgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.1 Fragen über Fragen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1.2 Wer fragt, bekommt Antworten …. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 Voll unagil? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.1 Agil vorgehen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2.2 Funktionierende Software vor umfassender Dokumentation . . . . . . . . . . . . . . 61.2.3 Dokumentation unterstützt Kommunikation. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.3 Wirkungsvolle Architektur dokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.3.1 Ziel 1: Architekturarbeit unterstützen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.3.2 Ziel 2: Architektur nachvollziehbar und bewertbar machen . . . . . . . . . . . . . . . 81.3.3 Ziel 3: Umsetzung und Weiterentwicklung leiten. . . . . . . . . . . . . . . . . . . . . . . . 91.3.4 Fremdwort Do|ku|men|ta|tion […zion] [lat.] . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4 Mission Statement für dieses Buch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.5 Über dieses Buch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.5.1 Für wen ich dieses Buch geschrieben habe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.5.2 Wie dieses Buch aufgebaut ist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.5.3 Wem ich Dankeschön sagen möchte. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2 Was Software architektur ist und worauf sie aufbaut . . . . . . . . . . . . .172.1 Softwarearchitektur-Freischwimmer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.1.1 Was ist Softwarearchitektur?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.1.2 Wie entsteht Softwarearchitektur? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.1.3 Wer oder was ist ein Softwarearchitekt? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.1.4 Ein Architekturüberblick auf n Seiten, n < 30. . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.2 Die Zielsetzung vermitteln. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.2.1 Jetzt kommt ein Karton! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.2.2 Virtueller Produktkarton (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . 242.2.3 Fallbeispiel: Schach-Engine „DokChess“ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.2.4 Tipps zum Erstellen von Produktkartons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.2.5 Fallbeispiel: Schachplattform „immer-nur-schach.de“ . . . . . . . . . . . . . . . . . . . 27

VI Inhalt

2.3 Den Kontext abgrenzen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.3.1 Systemkontext (Dokumentationsmittel). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.3.2 Fallbeispiel: Systemkontext „immer-nur-schach.de“. . . . . . . . . . . . . . . . . . . . . 302.3.3 Tipps zur Erstellung des Systemkontextes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.4 Im Rahmen bleiben. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.4.1 Warum Randbedingungen festhalten? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.4.2 Randbedingungen (Dokumentationsmittel). . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.4.3 Fallbeispiel: Randbedingungen „immer-nur-schach.de“. . . . . . . . . . . . . . . . . . 382.4.4 Tipps zum Festhalten von Randbedingungen . . . . . . . . . . . . . . . . . . . . . . . . . . 39

2.5 Geforderte Qualitätsmerkmale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.5.1 Was sind Qualitätsmerkmale? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.5.2 Qualitätsziele (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.5.3 Fallbeispiel: Qualitätsziele „immer-nur-schach.de“ . . . . . . . . . . . . . . . . . . . . . 442.5.4 Fallbeispiel: Qualitätsziele „DokChess“ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.5.5 Qualitätsmerkmale genauer beschreiben . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462.5.6 Qualitätsszenarien (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . . . . . . 472.5.7 Fallbeispiel: Qualitätsszenarien „immer-nur-schach.de“ . . . . . . . . . . . . . . . . . 482.5.8 Tipps zum Festhalten von Qualitätsszenarien . . . . . . . . . . . . . . . . . . . . . . . . . 50

2.6 Weitere Einflüsse und Hilfsmittel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.6.1 Stakeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.6.2 Persona (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542.6.3 Fallbeispiel: Persona „immer-nur-schach.de“ . . . . . . . . . . . . . . . . . . . . . . . . . . 552.6.4 Risiken. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572.6.5 Technische Risiken (Dokumentationsmittel). . . . . . . . . . . . . . . . . . . . . . . . . . . 582.6.6 Fallbeispiel: Technische Risiken „DokChess“ . . . . . . . . . . . . . . . . . . . . . . . . . . 582.6.7 Glossar (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3 Entscheidungen treffen und festhalten . . . . . . . . . . . . . . . . . . . . . . . . .613.1 Historisch gewachsen? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.2 Architekturentscheidungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

3.2.1 Architekturentscheidung (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . 623.2.2 Fallbeispiel: Spannende Fragen „DokChess“. . . . . . . . . . . . . . . . . . . . . . . . . . . 643.2.3 Tipps zur Formulierung von Fragestellungen . . . . . . . . . . . . . . . . . . . . . . . . . . 643.2.4 Fallbeispiel: Fragestellungen „immer-nur-schach.de“ . . . . . . . . . . . . . . . . . . . 66

3.3 Einflussfaktoren auf Entscheidungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.3.1 Den Überblick behalten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.3.2 Kreuztabellen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.3.3 Fallbeispiel: Einflüsse „immer-nur-schach.de“ . . . . . . . . . . . . . . . . . . . . . . . . . 723.3.4 Tipps zur Anfertigung von Kreuztabellen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

3.4 Kompakte Darstellung der Lösungsstrategie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743.4.1 Softwarearchitektur auf einem Bierdeckel? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.4.2 Lösungsstrategie (Dokumentationsmittel). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.4.3 Fallbeispiel: Lösungsstrategie „DokChess“ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.4.4 Als Ergänzung: ein Überblicksbild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783.4.5 Eine Architekturbewertung auf dem Bierdeckel . . . . . . . . . . . . . . . . . . . . . . . . 78

Inhalt VII

4 Plädoyer für eine feste Gliederung. . . . . . . . . . . . . . . . . . . . . . . . . . . . .794.1 Der jüngste Spieler fängt an! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794.2 Vorteile einer festen Struktur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804.3 arc42 – Vorschlag für eine Gliederung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

4.3.1 Was ist arc42? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824.3.2 Die Struktur der arc42-Vorlage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834.3.3 Wo funktioniert arc42 besonders gut? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854.3.4 arc42 in diesem Buch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

4.4 Alternativen zu arc42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874.4.1 Standards zur Architekturbeschreibung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874.4.2 Vorgehensmodelle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884.4.3 Architektur-Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904.4.4 Fachliteratur als Inspiration? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

5 Sichten auf Softwarearchitektur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .955.1 Strukturen entwerfen und festhalten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

5.1.1 Was ist was? Band 127: Unser Softwaresystem. . . . . . . . . . . . . . . . . . . . . . . . . 955.1.2 Schritte der Zerlegung dokumentieren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965.1.3 Bausteinsicht (Dokumentationsmittel). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975.1.4 Fallbeispiel: Bausteinsicht „DokChess“ (Ausschnitt) . . . . . . . . . . . . . . . . . . . . 985.1.5 Komponenten: Babylonische Sprachverwirrung 2.0. . . . . . . . . . . . . . . . . . . . . 995.1.6 Tipps zur Erstellung der Bausteinsicht . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005.1.7 Interaktionspunkte beschreiben. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.1.8 Schnittstellenbeschreibung (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . 1085.1.9 Fallbeispiel: Schnittstellen der Eröffnung in „DokChess“ . . . . . . . . . . . . . . . 110

5.2 Verschiedene Blickwinkel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135.2.1 Hat Mozart modelliert? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135.2.2 Fachliche Zerlegung vs. technische Zerlegung . . . . . . . . . . . . . . . . . . . . . . . . 1155.2.3 Fallbeispiel: Bausteinsicht „immer-nur-schach.de“. . . . . . . . . . . . . . . . . . . . . 117

5.3 Verhalten und Abläufe beschreiben . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.3.1 Abläufe in Entwurf und Dokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.3.2 Darstellungen für Abläufe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.3.3 Laufzeitsicht (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235.3.4 Fallbeispiel: Ablauf in DokChess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245.3.5 Fallbeispiel: Zustandsautomat XBoard (DokChess) . . . . . . . . . . . . . . . . . . . . 124

5.4 Die Dinge zum Einsatz bringen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255.4.1 Betriebsaspekte in der Architekturdokumentation . . . . . . . . . . . . . . . . . . . . 1265.4.2 Darstellungen für Verteilung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275.4.3 Verteilungssicht (Dokumentationsmittel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295.4.4 Fallbeispiel: „immer-nur-schach.de“. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

5.5 Alternative Vorschläge für Sichten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325.6 Muster kommunizieren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

5.6.1 Muster in der Softwareentwicklung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355.6.2 Wann sollte man Muster dokumentieren (und wo)? . . . . . . . . . . . . . . . . . . . . 1365.6.3 Einsatz von Mustern dokumentieren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365.6.4 Fallbeispiel: DokChess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

VIII Inhalt

6 Übergreifende Konzepte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396.1 Warum übergreifende Themen? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396.2 Themen und Lösungsoptionen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

6.2.1 Mögliche Themen für übergreifende Konzepte . . . . . . . . . . . . . . . . . . . . . . . . 1406.2.2 Typische Lösungsoptionen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

6.3 Themenauswahl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446.3.1 Wie wählt man Themen für die Dokumentation aus?. . . . . . . . . . . . . . . . . . . 1456.3.2 Fallbeispiel: Übergreifende Themen „DokChess“ . . . . . . . . . . . . . . . . . . . . . . 146

6.4 Eine Gliederungstechnik für Konzepte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486.4.1 Werkzeug: Warum? Was? Wie? Wohin noch?. . . . . . . . . . . . . . . . . . . . . . . . . . 1486.4.2 Gliederung für ein Konzept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506.4.3 Informeller Text für den Architekturüberblick . . . . . . . . . . . . . . . . . . . . . . . . 152

6.5 Tipps zur Erstellung übergreifender Konzepte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

7 Werkzeuge zur Dokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577.1 Notationen passgenau wählen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577.2 Toolparade zur Architekturdokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

7.2.1 Erstellung und Pflege . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1627.2.2 Verwaltung von Inhalten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687.2.3 Kommunikation von Lösungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

7.3 Repository: UML vs. Wiki. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727.3.1 Steht alles im Wiki? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737.3.2 Steht alles im UML-Tool? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767.3.3 UML-Tool + Wiki == Traumpaar? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

7.4 Wie auswählen?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

8 Lightfäden für das Vorgehen zur Dokumentation . . . . . . . . . . . . . . 1838.1 Während der Entwicklung dokumentieren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

8.1.1 Zielgruppen Ihrer Dokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1838.1.2 Dokumentationsmittel und Dokumente. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868.1.3 Womit anfangen? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898.1.4 Während der Arbeit: Kommunizieren und Pflegen. . . . . . . . . . . . . . . . . . . . . 190

8.2 Der Softwaredetektiv: Bestehendes Dokumentieren . . . . . . . . . . . . . . . . . . . . . . . . . . 1928.2.1 Auslöser für Dokumentationsbedarf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928.2.2 Mögliche Szenarien und Ziele des Dokumentierens im Nachhinein . . . . . . 1938.2.3 Sherlock Holmes vs. Die drei ???. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1948.2.4 Informationsquellen identifizieren. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958.2.5 Dokumentationsmittel unter der Lupe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1968.2.6 Exkurs: Werkzeuge zur Rekonstruktion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

8.3 Variationen von „Ein System“ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2068.3.1 Dokumentation von Systemlandschaften. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2068.3.2 Dokumentation von Frameworks und Blue Prints . . . . . . . . . . . . . . . . . . . . . 208

9 Architekturüberblick DokChess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2119.1 Einführung und Ziele . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

9.1.1 Aufgabenstellung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Inhalt IX

9.1.2 Qualitätsziele . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129.1.3 Stakeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

9.2 Randbedingungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169.2.1 Technische Randbedingungen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169.2.2 Organisatorische Randbedingungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169.2.3 Konventionen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

9.3 Kontextabgrenzung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2189.3.1 Fachlicher Kontext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2189.3.2 Technischer- oder Verteilungskontext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

9.4 Lösungsstrategie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209.4.1 Aufbau von DokChess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219.4.2 Spielstrategie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229.4.3 Die Anbindung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

9.5 Bausteinsicht . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239.5.1 Ebene 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239.5.2 XBoard-Protokoll (Blackbox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249.5.3 Spielregeln (Blackbox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259.5.4 Engine (Blackbox). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2269.5.5 Eröffnung (Blackbox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2279.5.6 Ebene 2: Engine (Whitebox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299.5.7 Zugsuche (Blackbox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299.5.8 Stellungsbewertung (Blackbox). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

9.6 Laufzeitsicht . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2329.6.1 Zugermittlung Walkthrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

9.7 Verteilungssicht . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2339.7.1 Infrastruktur Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

9.8 Konzepte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359.8.1 Abhängigkeiten zwischen Modulen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359.8.2 Schach-Domänenmodell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359.8.3 Benutzungsoberfläche . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2379.8.4 Plausibilisierung und Validierung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2389.8.5 Ausnahme- und Fehlerbehandlung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2399.8.6 Logging, Protokollierung, Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2399.8.7 Testbarkeit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

9.9 Entwurfsentscheidungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2429.9.1 Wie kommuniziert die Engine mit der Außenwelt? . . . . . . . . . . . . . . . . . . . . 2429.9.2 Sind Stellungsobjekte veränderlich oder nicht? . . . . . . . . . . . . . . . . . . . . . . . 244

9.10 Qualitätsszenarien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2479.10.1 Qualitätsbaum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2479.10.2 Bewertungsszenarien. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

9.11 Risiken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2499.11.1 Risiko: Anbindung an das Frontend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2499.11.2 Risiko: Aufwand der Implementierung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2499.11.3 Risiko: Erreichen der Spielstärke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

9.12 Glossar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

X Inhalt

10 Stolpersteine der Architektur dokumentation . . . . . . . . . . . . . . . . . 25310.1 Probleme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25310.2 Fiese Fallen … . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25510.3 … und wie man sie umgeht oder entschärft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25710.4 Reviews von Architekturdokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Glossar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Literaturverzeichnis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Stichwortverzeichnis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Geleitwort zur 1. Auflage

Dokumentation – Unwort der IT?Viele IT-Systeme gelten zu Recht als schlecht erweiterbar, schwer verständlich und unge-mein komplex. Teilweise liegt das an ihrer mangelhaften Dokumentation, an fehlenden oder unklaren Erläuterungen. Bei anderen Systemen begegnet mir das Gegenteil: Hunderte von Dokumenten, ungeordnet auf Netzlaufwerken, ohne klaren Einstiegspunkt. Kein Wunder, dass Dokumentation als Unwort gilt.Die meisten Teams, die ich in meinem IT-Leben begleitet habe, konnten gut bis sehr gut programmieren, viele haben ausgezeichnete technische Konzepte entwickelt und umgesetzt. Aber kaum eines dieser Teams konnte auch nur halbwegs ordentlich dokumentieren. Oft als lästige Nebensache verflucht, mit fadenscheinigen Argumenten auf „später“ verschoben oder von Anfang an aufs Abstellgleis verbannt: Dokumentation gilt in Projekten als uncool oder, schlimmer noch, als Strafarbeit: Doku – das sollen andere machen.Hinter dieser weit verbreiteten, negativen Haltung steckt Unsicherheit: Kaum ein Entwick-ler, Architekt oder Projektleiter hat jemals gelernt, über Systeme zielorientiert, methodisch und mit moderatem Aufwand zu kommunizieren – und Dokumentation ist schriftliche (d. h. persistente) Kommunikation.Genau dafür stellt dieses Buch großartige, praxiserprobte und direkt umsetzbare Lösungen bereit: Sie erfahren, wie Sie mit einfachen Mitteln die Anforderungen an langfristige, lesbare und verständliche Dokumentation erfüllen können. Stefan Zörner erklärt Ihnen, wie Sie so-wohl den großen Überblick als auch das notwendige kleine Detail für Ihre Leser sachgerecht aufbereiten und darstellen. Besonders freut mich natürlich, dass er etwas Werbung für unser (freies) arc42-Template macht :-)Ein echtes Novum finden Sie in Kapitel 6 über technische Konzepte: Überall heißt es in der Praxis: „Wir brauchen ein Konzept für <schwieriges technisches Problem>“ … aber niemand erklärt uns, wie solche Konzepte denn genau aussehen sollen. Wir überlegen jedes Mal neu, in welcher Struktur wir unsere Lösungsideen darstellen und wie wir argumentieren sollen. Stefan eilt mit diesem Buch zu Hilfe: Er hat (unterstützt durch Uwe Vigenschow) aus den langjährigen Erfahrungen von Lernmethodikern und Hirnforschern genau die Hinweise extra hiert, die wir für verständliche, nachvollziehbare und klare Konzepte benötigen. (Neu-gierig geworden? Blättern Sie direkt mal zu Seite 148 und überfliegen das Vier-Quadranten-Modell.)Aber damit nicht genug: Getreu dem Motto, dass Beispiele die besten Lehrmeister sind, hat Stefan ein wirklich cooles System entworfen, gebaut und für dieses Buch vorbildlich doku-mentiert: Seine Schach-Engine DokChess illustriert, wie gute Dokumentation aussehen kann (und spielt außerdem noch ganz passabel Schach).

XII Geleitwort zur 1. Auflage

Ich wünsche Ihnen Freude mit diesem Buch. Als Reviewer durfte ich ja schon vor längerer Zeit frühe Versionen testlesen. Mehr als einmal haben mir Stefans Ratschläge in konkreten Projektsituationen seitdem geholfen.May the force of the proper word and diagram be with you.

Köln, im März 2012Gernot Starke

Überblick: Dokumentationsmittel im Buch

Die Abbildung zeigt alle im Buch vorgestellten Dokumentationsmittel („Zutaten“) für Soft-warearchitektur. Verbindungslinien visualisieren wichtige methodische Zusammenhänge. Die Pfeile an den Linien geben die Leserichtung für die Beschriftung an (Beispiel: Bausteinsicht verfeinert Systemkontext).

Architektur-entscheidung

Randbedingungen

Technische Risiken

Konzept

Bausteinsicht

Laufzeitsicht

Schnittstellen-beschreibung

SystemkontextPersona

Produktkarton

Glossar

klingen an in

grenzt Inhalte ein

macht lebendig

liefert Quellen liefert Quellen

beschreibt Interaktionspunkte aus

verfeinert

konkre-tisieren

konkretisiert

adressiertleiten

verweist auf

verweist auf

treiben

setzt

Verteilungssicht

konkretisiert Nutzung von

nutzt API aus

ergänzt umDynamik

machen bewertbar

zeigt Deployment von

beeinflusst

Klärt wichtige Begriffe ausallen Dokumentationsmitteln

Dokumentationsmittel des Buchs mit wichtigen Zusammenhängen

Der Tabelle auf der nächsten Seite können Sie entnehmen, auf welcher Seite im Buch Sie den Steckbrief zum betreffenden Dokumentationsmittel finden.

XIV Überblick: Dokumentationsmittel im Buch

Überblick über die Dokumentationsmittel

Dokumentationsmittel Nutzen SteckbriefArchitektur entscheidung Nachvollziehbare Darstellung einer zentralen,

risikoreichen EntscheidungSeite 69

Bausteinsicht Visualisierung der Struktur des Softwaresystems und wie die Teile voneinander abhängen

Seite 104

Glossar Etablieren eines einheitlichen Wortschatzes im ganzen Vorhaben

Seite 60

Laufzeitsicht Visualisierung von dynamischen Strukturen und Verhalten, vor allem von Abläufen

Seite 123

Lösungsstrategie Stark verdichteter Architekturüberblick; Gegenüber­stellung der wichtigsten Ziele und Lösungsansätze

Seite 76

Persona Archetypische Beschreibung einer Personengruppe und deren Ziele (Stakeholder)

Seite 56

Produktkarton Plakative Darstellung der wesentlichen Funktionen, Ziele und Merkmale des Systems

Seite 28

Qualitätsszenarien Konkretisierung von Qualitätsanforderungen in kurzen, beispielhaften Sätzen

Seite 52

Qualitätsziele Motivation der wichtigsten an das System gestellten Qualitätsanforderungen

Seite 45

Randbedingungen Sammlung der technischen bzw. organisatorischen Vor­gaben, die beim Entwurf einzuhalten sind (oder waren)

Seite 41

Schnittstellen­beschreibung

Detaillierte Beschreibung, wie ein Baustein Funktio­nalität bereitstellt (oder welche er benötigt)

Seite 112

Systemkontext Visualisierung der Fremdsysteme und Benutzer, mit denen das System interagiert

Seite 34

Technische Risiken Beschreibung der Risiken, die Einfluss auf die Soft­warearchitektur haben (oder hatten)

Seite 59

Übergreifendes Konzept Darstellung eines übergreifenden Themas, zur Ver­einheitlichung im System oder zur Detaillierung eines Ansatzes

Seite 152

Verteilungssicht Visualisierung der Zielumgebung, der Inbetriebnahme und des Betriebs des Systems

Seite 130

3 Entscheidungen treffen und festhalten

„The life of a software architect is a long (and sometimes painful) succession of suboptimal decisions made partly in the dark.“ 1

Philippe Kruchten

Im letzten Kapitel haben Sie Dokumentationsmittel kennengelernt, um die treibenden Einflüsse auf Ihre Softwarearchitektur festzuhalten. Architekturen zu entwerfen, heißt im Wesentlichen, Entscheidungen zu treffen. Den maßgeblichen Entscheidungen räumt dieses Kapitel einen besonderen Stellenwert ein. Ich zeige, wie Sie sie treffen und geeignet festhalten können, um das Ziel der Nachvollziehbarkeit zu adressieren.

■■ 3.1■ Historisch gewachsen?

1815 – Europa im Umbruch. Napoleon verliert bei Waterloo seine letzte Schlacht. Mittlerweile haben Historiker reichlich Papier veröffentlicht, um die Gefechtsgeschehnisse zu dokumen-tieren und zu bewerten. Sie sind sich nicht in allen Punkten einig. Die Entscheidungen Napoleons 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 seinem Handeln entdeckt zu haben. Sie können aber nur spekulieren, ob Napoleon sie aus Unwis-senheit beging oder ob eine Absicht dahinter stand, die sie nicht kennen.

200 Jahre späterEin Softwaresystem in der Entwicklung. Architekturentscheidungen, also solche, die im wei-teren Verlauf nur schwer zurückzunehmen sind, geben den Rahmen für die Umsetzung vor. Sie sind ein zentrales Arbeitsergebnis – Architektur erfolgreich umzusetzen, heißt vor allem, sie im Team zu kommunizieren. Und insbesondere sollten Sie Architekturentscheidungen geeignet festhalten. Warum eigentlich? Damit spätere Geschichtsschreiber Ihr Projekt leichter erforschen können? So lange brauchen Sie in der Regel nicht zu warten. Schon der erste neue Mitarbeiter im Team wird viele Fragen stellen, die auf zentrale Entscheidungen abzielen.

1 Deutsch etwa: „Das Leben eines Softwarearchitekten ist eine lange (und manchmal schmerzvolle) Folge von suboptimalen Entscheidungen, die teilweise im Dunkeln getroffen werden.“

62 3 Entscheidungen treffen und festhalten

„Warum habt ihr das denn mit X-Framework gemacht? Y-Framework ist doch viel besser!“ Nicht jeder im Team kann sich vielleicht noch erinnern, was damals für X-Framework sprach. Gerade in wachsenden Projekten, die häufig neue Mitarbeiter integrieren, kommt es zu den immer gleichen Debatten, die leicht vermieden oder zumindest abgekürzt werden können. Auch andere Projektbeteiligte haben Fragen. Und neben der Wissensvermittlung und -erhal-tung im Team sind dokumentierte Entscheidungen auch für Architekturbewertungen und Reviews unerlässlich.

Wer zu spät kommt …Wenn Sie und Ihr Team zentrale Entscheidungen hingegen zu spät dokumentieren, sind der Findungsprozess und die Intention dahinter bereits in Vergessenheit geraten. Falls zu einem späteren Zeitpunkt eine Entscheidung neu bewertet und ggf. geändert werden muss, 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 – Sie erinnern sich –: „Das ist historisch gewachsen.“

■■ 3.2■ Architekturentscheidungen

Das Wort „Entscheidung“ wird sowohl für die Fragestellung verwendet als auch für das Ergebnis. Einer Dokumentation können Sie typischerweise viele Entscheidungen (im Sinne von Ergebnis) entnehmen. In jedem Vorhaben gibt es einige wenige Fragestellungen, deren Beantwortung einen vergleichsweise großen Einfluss auf die Lösung hat, beziehungsweise wo falsche Entscheidungen das Scheitern bedeuten können (Waterloo-Klasse). Zu diesen zentralen Punkten wollen wir mehr festhalten als das bloße Ergebnis.

3.2.1■ Architekturentscheidung (Dokumentationsmittel)

In der Praxis haben sich einfache Templates bewährt. Für jede zentrale Entscheidung fra-gen sie die gleichen Dinge ab und stellen so alle Architekturentscheidungen der Lösung gleichförmig dar.Bild 3.1 zeigt einen Strukturierungsvorschlag2, der zweierlei leistet: Erstens hilft er Ihnen, die Entscheidung zu bearbeiten und zu einem Ergebnis zu führen. Und zweitens gibt er eine Gliederung vor, wie Sie die Entscheidung geeignet festhalten. Beispielsweise mit Hilfe einer Vorlage – die Hauptäste ergeben dann die Kapitelüberschriften.An den einzelnen Ästen der Mindmap sind Fragen angehängt, die Sie in Ihre Vorlage mit aufnehmen können.3 Sie müssen diese Fragen nicht sklavisch beantworten. Vielmehr sollen sie Sie bei einer konkreten Architekturentscheidung, etwa in einem Workshop, leiten, anregen und unterstützen. Gehen wir die Äste der Reihe nach durch!

2 Eine erste Fassung dieser Struktur ist in [Zörner2008] erschienen.3 Die Webseite zum Buch bietet entsprechende Vorlagen als Startpunkt für Sie zum Download an.

3.2 Architekturentscheidungen 63

Architektur-entscheidung

festhalten

(1) FragestellungWas genau ist das Problem?

Warum ist es für die Architektur relevant?

Welche Auswirkung hat die Entscheidung?

(2) EinflussfaktorenWelche festen Randbedingungen haben wir einzuhalten?

Welche Qualitätsziele sind zu beachten?

Welche Risiken sind betroffen?

(3) Annahmen

Welche Annahmen haben wir getroffen?

Welche Annahmen können wie vorabüberprüft werden?

MIt welchen neuen Risikenmüssen wir rechnen?

(4) BetrachteteAlternativen

Welche Lösungsoptionen ziehen wir in die nähere Auswahl?

Wie bewerten wir jede einzelne?

Welche Optionen schließen wir bewusst aus?

(5) EntscheidungWer hat die Entscheidung getroffen?

Wie ist sie begründet?

Wann wurde entschieden?

Bild 3.1 Struktur und Leitfragen zur Bearbeitung einer Architekturentscheidung

Zur FragestellungEntscheidungen im Projekt gibt es viele. Stellen Sie überzeugend dar, warum die hier betrach-tete Fragestellung tatsächlich eine Architekturentscheidung ist. Die Auswahl der richtigen Fragestellungen für die Architekturbeschreibung ist ein wesentlicher Erfolgsfaktor für die Nachvollziehbarkeit.

Relevante EinflussfaktorenMit den Dokumentationsmitteln aus Kapitel 2 haben Sie mögliche Einflussfaktoren auf die Softwarearchitektur festgehalten. Von diesen sind bestimmte Randbedingungen, Qualitäts-ziele, Risiken etc. tonangebend für diese Fragestellung. Identifizieren und nennen Sie diese.

AnnahmenDie beschriebenen Einflussfaktoren grenzen die Fragestellung nicht völlig ein, sondern las-sen Ihnen Entscheidungsspielraum. Sie treffen Annahmen, welche die möglichen Optionen weiter reduzieren oder sich auf die Bewertung der Optionen auswirken. Im Grunde wird jede Architekturentscheidung unter gewissen (oft impliziten) Annahmen getroffen.

„Entscheidungen sind immer dann nötig, wenn Wissen fehlt und trotzdem gehandelt werden muss.“ [Wohland+2012]

In vielen Fällen machen getroffene Annahmen dem Außenstehenden erst begreiflich, war-um eine Entscheidung so und nicht anders ausgefallen ist. Halten Sie sie fest (und machen Sie sie sich dadurch auch noch einmal bewusst). Annahmen zählen zu den Dingen, die im Nachhinein beinahe unmöglich zu rekonstruieren sind.

64 3 Entscheidungen treffen und festhalten

Betrachtete AlternativenJe nach Fragestellung nehmen Sie zwei oder mehr Optionen in die engere Auswahl, wobei Sie die Anzahl aufgrund des Aufwandes (für die Entscheidung und auch für die Dokumentation) in der Regel klein halten. Machen Sie klar, wie Sie zur Auswahlliste gekommen sind. Gibt es auf den ersten Blick naheliegende Optionen, die Sie aufgrund von Einflussfaktoren oder Annahmen bewusst ausgeschlossen haben?Bewerten Sie dann die Alternativen bezüglich der Fragestellung. Wie verhalten diese sich in Bezug auf die Einflussfaktoren? Mit einer Kreuztabelle (siehe 3.3.2) können Sie die einzelnen Optionen klar und kompakt gegen Ihre Bewertungskriterien halten.

Zur EntscheidungWie sieht das Ergebnis aus, und wie begründen Sie es? Um spätere Rückfragen schnell adressie ren zu können, halten Sie denjenigen, der entschieden hat (oder diejenigen), fest oder zumindest die an der Entscheidung Beteiligten. Ebenso den Zeitpunkt, wann die Ent-scheidung getroffen wurde. Manche Optionen gab es zu diesem Zeitpunkt vielleicht noch gar nicht, oder die betreffenden Lösungen waren nicht ausgereift genug.

3.2.2■ Fallbeispiel: Spannende Fragen „DokChess“

Im Rahmen der Realisierung der Schach-Engine DokChess stellte sich eine ganze Reihe von Fragen. Hier eine Auswahl zur Illustration:4

� Wie zerfällt das System in Teile? Wie hängen die verschiedenen Teile voneinander ab? � Wie wird die Spielsituation („Stellung“) als Datenstruktur abgebildet? � Sind Stellungsobjekte veränderlich oder nicht? � Wie kommuniziert die Engine mit der Außenwelt? � Welches Eröffnungsbibliotheksformat wird unterstützt? Wie? � Wie stellen wir fest, ob die Engine gut genug spielt?

Im Folgenden finden Sie einige Hinweise, damit solche Fragen in einer Architekturdokumenta-tion nicht wie hier im Beispiel einfach vom Himmel fallen, sondern sich in das Ganze einfügen.

3.2.3■ Tipps zur Formulierung von Fragestellungen

Wie kommt man auf Fragestellungen für Entscheidungen?Auch wenn sich viele Fragen dem Team oft von ganz allein stellen („Wie [machen|erreichen|lösen|verhindern|…] wir eigentlich XY?“), möchte ich Ihnen Werkzeug an die Hand geben, um Kandidaten für Fragestellungen methodisch herzuleiten. In einem guten Architektur-überblick passt alles zueinander („Roter Faden“). Deswegen basieren die folgenden Ideen für Ihr Brainstorming auf den bisher besprochenen Dokumentationsmitteln.

4 Zwei besonders interessante Fragen finden Sie in Kapitel 9 („Architekturüberblick DokChess“) nach dem vorge­schlagenen Schema bearbeitet.

3.2 Architekturentscheidungen 65

� Wandern Sie den Systemkontext ab. Wie binden Sie die Akteure jeweils an? � Gehen Sie die Qualitätsziele durch. Ist klar, mit welchen Strategien Sie diese jeweils errei-chen? Welche Alternativen sehen Sie?

� Welche Qualitätsszenarien sind Ihrer Einschätzung nach schwer umzusetzen? Woran liegt das?

� Welche Highlevel-Entscheidung ließe sich im weiteren Projektverlauf nur schwer zurück-nehmen (und ist keine Rahmenbedingung)?

� Wo lassen Ihnen die Rahmenbedingungen viel Spielraum? � Welche Fragen werfen die identifizierten Risiken auf? Gibt es Optionen, um sie zu be-herrschen?

Was sind typische Fragestellungen für Architekturentscheidungen?Jedes Vorhaben ist anders und verfolgt seine eigenen Architekturziele. Auch vermeintlich „kleine“ Fragestellungen können große Auswirkungen haben. Nichtsdestotrotz gibt es bestimmte Typen von Fragen („übliche Verdächtige“), die immer wieder als Architekturent-scheidungen auftauchen: � Welche Oberflächen erhalten die Benutzer? � Wie binden wir Fremdsystem XY an? � Wie kommunizieren Bestandteile unseres Systems untereinander? � Wie adressieren wir querschnittliche Themen (zum Beispiel Persistenz, Verteilung …)? � Implementieren wir eine geforderte Funktionalität selbst, oder verwenden wir eine beste-hende Lösung („Make or Buy“, „Make or Take“)?

� Welches Produkt/welche Technologie verwenden wir für XY?

Wie viele Ausgänge sollte eine Fragestellung haben?Eine Fragestellung hat mindestens zwei Ausgänge, damit eine sinnvolle Entscheidung ge-troffen werden kann. Manchmal stoße ich in Dokumentationen auf Fragen, die „gefühlt“ nur einen haben, zum Beispiel in der Form:

Sollen wir OpenDuperPlus benutzen?Auf diese Frage gibt es zwei Antworten (ja und nein), aber eine impliziert sofort die nächste Frage: Was machen wir, wenn wir OpenDuperPlus nicht verwenden können oder wollen? Bei manchem Leser sicher auch: Was ist OpenDuperPlus5?In solch einem Fall gilt es eine ergebnisoffene Fragestellung herauszuarbeiten. Was be zwecken Sie mit der Verwendung von OpenDuperPlus? Welches Problem löst es? Das konkrete Produkt sollte dann eine Alternative sein.Es ist kein Zufall, dass Fragen wie die obige insbesondere in solchen Architekturbeschreibun-gen zu finden sind, wo im Nachhinein dokumentiert wurde. Der Ausgang ist dann natürlich, dass OpenDuperPlus benutzt wird. Das betreffende Unterkapitel der Architekturbeschreibung heißt nur „OpenDuperPlus“ oder „Warum OpenDuperPlus?“. Es stellt die Vorzüge der gewähl-ten „Alternative“ dar. Genau solche Effekte soll die hier vorgeschlagene Struktur verhindern.

5 Den Namen habe ich mir ausgedacht, um den Effekt auch bei Ihnen zu erzielen. Siehe auch „Wie betitelt man eine Architekturentscheidung geschickt?“

66 3 Entscheidungen treffen und festhalten

Auch die Vergabe eines guten Titels kann wirkungsvoll unterstützen. Nennen Sie die Unter-kapitel nicht „Entscheidung 1“, … „Entscheidung N“ (schon gesehen).

Wie betitelt man eine Architekturentscheidung geschickt?In eine Architekturbeschreibung werden die zentralen Entscheidungen typischerweise zu einzelnen (Unter-)Kapiteln, in einem Wiki zu einzelnen Seiten. In beiden Fällen spielt der Titel (also die Kapitel- bzw. Seitenüberschrift) eine große Rolle. Er landet im Inhaltsverzeichnis und je nach Formatierung in Kopf- oder Fußzeile. Im Falle des Wikis tritt er prominent in Suchergebnissen auf.Während der Titel bei vielen anderen vorgestellten Werkzeugen klar ist (man nennt das Kapitel einfach wie das Dokumentationsmittel), gibt es bei Architekturentscheidungen zwei typische Optionen: � Thema oder Fragestellung der Entscheidung (z. B. „Persistenz“, „Wie persistieren wir …?“) � Ergebnis der Entscheidung (z. B. „O/R-Mapping mit Hibernate zur Persistenz“)

Die erste Option hat den Vorteil, dass Sie ihn bereits vergeben können, bevor das Ergebnis fest-steht, also schon während der Erarbeitung. Das entspricht dem wünschenswerten Vorgehen, Entscheidungen bereits festzuhalten, während man sie fällt. Wird die Entscheidung getroffen oder geändert, kann der Titel stabil gehalten werden. Ich persönlich präferiere diese Option und empfinde dabei eine richtige Fragestellung (nicht nur das Thema) als sehr lebendig.Die zweite Variante punktet dadurch, dass bereits an der Überschrift, also beim Überfliegen eines Inhaltsverzeichnisses, das Ergebnis abzulesen ist. Auch in dieser Option sollte nicht nur die favorisierte Alternative selbst als Überschrift gewählt werden („OpenDuperPlus“). Lassen Sie die Problemstellung mit anklingen. Es ist auch ein Kompromiss denkbar, bei dem nach Treffen der Entscheidung das Ergebnis mit im Titel landet. Beim Revidieren einer Entscheidung muss bei dieser Option der Titel angepasst werden.

3.2.4■ Fallbeispiel: Fragestellungen „immer­nur­schach.de“

Im Folgenden stelle ich wichtige offene Entscheidungen für immer-nur-schach.de vor und motiviere jeweils die Fragestellung. Für eine dokumentierte Architekturentscheidung ist der kurze Text jeweils ein Beispiel für das einleitende Unterkapitel „Fragestellung“ (vgl. Bild 3.1, Ast 1). Die Entscheidungen sind hier aus Platzgründen nicht vollständig dargestellt. Ausgearbeitete Beispiele für DokChess finden Sie in Kapitel 9.

1. Auf welcher Ablaufumgebung basiert der Server?Bei immer-nur-schach.de spielen die Gegner auf unterschiedlichen Clients gegeneinander. Die Kommunikation erfolgt über einen in Java zu realisierenden Server. Für diesen gibt es Anforderungen, unter anderem bezüglich Zuverlässigkeit, Portierbarkeit und Sicherheit. Das legt die Verwendung eines Java-basierten Applikationsservers nahe. Hier ist eine konkrete Lösung auszuwählen. Offen ist dabei, ob ein kommerzielles Produkt oder eine Open-Source-Implementierung verwendet wird. Wird gezielt für einen konkreten Server realisiert, oder soll durch Beschränkung auf Standards (z. B. Java EE Web Profile) mehr Flexibilität erreicht

3.2 Architekturentscheidungen 67

werden? Diese erreicht man vielleicht besser, indem man von einer für alle Teile von immer-nur-schach.de einheitlichen Ablaufumgebung absieht (Stichwort Microservices).

2. Wo wird der Zustand einer laufenden Online­Partie gehalten?Während eine Partie läuft, tauschen beide Gegner ihre Züge über den Server aus. Der Zustand einer Partie umfasst unter anderem die Situation auf dem Brett und den bisherigen Verlauf. Am Ende einer Partie muss diese persistiert werden, um später darauf zurückgreifen zu können. Wo liegt der Zustand vor Spielende? Zu den Optionen zählen die Clients der Spieler, der Server und eine Datenbank. Auch eine Kombination ist denkbar. Die Entscheidung hat Einfluss auf die Benutzbarkeit und Zuverlässigkeit von immer-nur-schach.de.

3. Welches Programmiermodell/Framework wird für den Server verwendet?In Abhängigkeit von der Ablaufumgebung (siehe oben) stehen verschiedene querschnittli-che Funktionalitäten zur Verfügung (Komponentenmodell, Konfiguration, Transaktionen, Persistenz, Sicherheit) oder auch nicht. Soll auf ein Applikationsframework zurückgegrif-fen werden, um fehlende Aspekte und zukünftige Erweiterungen (Stichwort Wartbarkeit) leichter umsetzen zu können oder reicht das Programmiermodell des Servers aus? Zu den Alternativen zählen Java EE, das Spring Framework und OSGi, wobei sich die genannten nicht wechselseitig ausschließen.

4. Wo werden Daten persistiert?Im Rahmen von immer-nur-schach.de sind unterschiedliche Dinge zu speichern, zum Bei-spiel Mitgliederdaten und gespielte Partien. Sie wachsen mit der Zeit an; Mitglieder und Schachpolizisten müssen sie effizient abfragen können. Als Speichertechnologien kommen grundsätzlich (mindestens) Dateien, relationale Datenbanken und NoSQL-Lösungen in Betracht. Dabei muss nicht zwingend eine Option das Speichermedium für alles sein. Die Entscheidung hat Einfluss auf die Zuverlässigkeit, Wartbarkeit, Effizienz und Portierbarkeit.

5. Wie werden Daten persistiert?In Abhängigkeit vorheriger Entscheidungen ist unter Umständen noch offen, wie auf Spei-chermedien zugegriffen wird. Kommt eine Bibliothek oder ein Persistenzframework zum Einsatz, oder reichen die Bordmittel des Programmiermodells bzw. des Frameworks bereits aus? Unter Umständen können auch hier nicht mit einer Lösung alle Anforderungen zu Wartbarkeit und Effizienz befriedigend erfüllt werden.

6. Wie wird die Web­Applikation realisiert?Viele Mitglieder greifen über einen Browser auf die Plattform zu. Zu kaum einem Thema gibt es in Java mehr Optionen als zu Webframeworks; auch die Auswahl der Oberflächentechnolo-gien (HTML5, JavaScript Frameworks, …) steht aus. Benutzbarkeit spielt für immer-nur-schach.de eine große Rolle, die Entscheidung hat auch Einfluss auf die Wartbarkeit der Lösung. Ähnlich wie bei der Persistenz ist bei dieser Frage das Programmiermodell interessant. Welche Möglichkeiten bietet es selbst? Welche Zusatzbibliotheken werden unterstützt? …

68 3 Entscheidungen treffen und festhalten

7. Wie interagieren Clients und Server bei Partien miteinander?Eine besondere Herausforderung stellt die Interaktion zwischen den Gegnern einer Partie miteinander dar. Sie läuft über den Server. Wie bekommt zum Beispiel ein Web-Client mit, dass der Gegner gezogen hat? Fragt er regelmäßig (z. B. Polling alle 2 s) nach, oder wird eine völlig andere Lösung (z. B. Push-Nachrichten, anderes Protokoll, etwa WebSocket) gewählt. Die Entscheidung wirkt auf Benutzbarkeit und Effizienz und hat Wechselwirkungen mit Ablaufumgebung und Randbedingungen bezüglich der Clients. Neben Browsern müssen auch die geforderten und ggf. zukünftigen mobilen Clients bedacht werden. Mit welcher Technologie soll eine entsprechende Remote-API zur Verfügung gestellt werden?

8. Wird für alle Benutzergruppen die gleiche Clienttechnologie verwendet?Neben den Mitgliedern müssen auch andere (konkret Schachpolizisten, Administratoren) auf die Plattform zugreifen. Wird für die Oberflächen aller Anwendergruppen die gleiche Clienttechnologie verwendet, oder werden für bestimmte z. B. auch Rich Clients oder Kom-mandozeilenwerkzeuge realisiert?

9. Wie wird die Forenfunktionalität abgebildet?Im Rahmen von immer-nur-schach.de ist ein Forum für die Mitglieder gefordert. Hier ist zu entscheiden, ob man diese Funktionalität selbst implementiert oder eine Lösung integriert („Make or buy?“). Im Falle eines Fremdproduktes ist dieses auszuwählen. Die Entscheidung wirkt sich vor allem auf die Benutzbarkeit, Wartbarkeit und Portierbarkeit aus.

10. Wie wird die Internet­Werbung realisiert?Die Internet-Werbung („AdServer“) soll nicht selbst implementiert werden. Stattdessen ist entweder ein Fremdprodukt auszuwählen, das immer-nur-schach.de hostet, oder eine Platt-form auszuwählen, welche die Funktionalität anbietet. In beiden Fällen muss die Werbung geeignet in die Oberflächen von immer-nur-schach.de eingebettet werden. Die Entscheidung hat Einfluss auf Wartbarkeit und Portierbarkeit.

Beeinflussungen

1. AblaufumgebungServer

3. Programmiermodell/Framework Server

9. Foren-funktionalität

10. Internet-Werbung

5. Persistenz-framework

8. VerschiedeneClienttechnologien

6. Web-applikationen

2. Zustandlaufender Partien

4. Persistenz-technologie

7. Interaktion Client/Server bei Partien

Bild 3.2 Thematische Beeinflussungen der Fragestellungen

3.2 Architekturentscheidungen 69

Die Themen der Fragestellungen sind teilweise voneinander abhängig, sie beeinflussen sich. Bild 3.2 zeigt die Zusammenhänge. Sie können die Beziehungen bereits während des Entwurfes in dieser Form visualisieren, es hilft Ihnen bei der Arbeit. Wertvoll ist so eine Dar-stellung aber auch, um sich im Rahmen der Dokumentation einen Überblick zu verschaffen (siehe auch nächstes Unterkapitel). Die Lösung der Fragestellungen kann sich wechselseitig beeinflussen, wie in Bild 3.2 bei Frage 1 und 3. Wenn die Entscheidungen getroffen werden, bleibt typischerweise nur eine Richtung übrig, die oft die chronologische ist (Beispiel: wir haben uns für Java EE als Programmiermodell entschieden, und das beeinflusste die Ent-scheidung für den Applikationsserver WildFly als Ablaufumgebung). Die Dokumentation sollte dies berücksichtigen, und bei Verwendung einer Darstellung wie Bild 3.2 innerhalb eines Architekturüberblickes sollte bereits aus der Beschriftung klar hervorgehen, welchen Sachverhalt (z. B. Zeitpunkt) sie zeigt.

Steckbrief: Dokumentationsmittel „Architekturentscheidung“Synonym: Entwurfsentscheidung

Zweck:Nachvollziehbare Darstellung der zentralen Entscheidungen, im Architektur-überblick an prominenter Stelle versammelt zum schnellen Zugriff.

Form:Textuell, je Entscheidung ein kurzes Dokument/Unterkapitel mit stets gleicher Struktur, zum Beispiel wie hier vorgeschlagen: � Fragestellung � Relevante Einflussfaktoren � Getroffene Annahmen � Betrachtete Alternativen � Begründete Entscheidung

Um Zusammenhänge überblicksartig darzustellen, zum Beispiel ergänzt um Kreuztabellen und Beeinflussungsdiagramme.

Checkliste für den Inhalt (pro Architekturentscheidung): � Wird plausibel dargestellt, warum die Fragestellung architekturrelevant ist? � Ist die Fragestellung offen formuliert? Lässt sie Alternativen zu? � Sind die Einflussfaktoren (vor allem die Qualitätsziele!) konsistent zur restlichen Architekturdokumentation?

� Ist die Auswahl der Alternativen nachvollziehbar? � Werden die Alternativen ergebnisoffen gegeneinander abgewogen? � Ist die Begründung für die Entscheidung schlüssig aus den Einflussfaktoren hergeleitet?

� Ist festgehalten, wer an der Entscheidung beteiligt war und wann sie getroffen wurde?

70 3 Entscheidungen treffen und festhalten

Checkliste für die ausgewählten Entscheidungen in einem Architekturüberblick: � Begünstigt die Reihenfolge der dargestellten Entscheidungen ein sequenzielles Lesen?

� Haben die Titel (Überschriften) der Entscheidungen die gleiche Form? � Ist die Anzahl der ausgewählten Entscheidungen angemessen (Praxistipp für den Überblick: 5 +/– 2)?

Ablageort arc42:Abschnitt 9: „Entwurfsentscheidungen“

Übungsaufgabe 3: Fragestellungen formulieren, Entscheidung festhaltenSammeln Sie stichpunktartig Fragestellungen, deren Beantwortung Einfluss auf die Architektur des Squeezebox Servers hatte. Wählen Sie davon eine aus, die Sie besonders interessant finden und deren Antwort Sie rekonstruieren können. Bearbeiten Sie diese Fragestellung nach dem Schema der Mindmap (Bild 3.1). Bei den Lösungsalternativen können Sie sich von folgenden Fragen leiten lassen: � Wie hätte man das anders lösen können? � Wie hätten Sie das gemacht?

Diskutieren Sie Stärken und Schwächen der Alternativen, zum Beispiel indem Sie sie gegen Qualitätsszenarien halten. Treffen Sie Annahmen, wo Ihnen Wissen fehlt, und dokumentieren Sie diese. Formulieren Sie Fragen, die Sie den Entwick-lern stellen würden, um mehr Klarheit zu bekommen.Insgesamt (Liste der Fragestellungen, ausgearbeitete Entscheidung) sollte Ihre Lösung drei DIN-A4-Seiten nicht übersteigen.

■■ 3.3■ Einflussfaktoren auf Entscheidungen

Kapitel 2 beschreibt Einflussfaktoren, die auf Entscheidungen wirken. Wäre das Ergebnis in der Dokumentation eine Reihe kurzer Kapitel je Entscheidung (oder einzelne Seiten im Wiki), ginge der Überblick schnell verloren. Wenn Sie effizient mit den Ergebnissen weiterarbeiten wollen, sollten Sie diesen aber behalten.

3.3.1■ Den Überblick behalten

In der Praxis stellen sich im Zusammenhang mit der Nachvollziehbarkeit der Softwarearchi-tektur und auch ihrer Weiterentwicklung oft Fragen wie diese:

3.3 Einflussfaktoren auf Entscheidungen 71

� Welche Entscheidungen beeinflussen die Erreichung eines bestimmten Qualitätsziels? � Randbedingung XY hat sich geändert, welche Entscheidungen sollten wir daraufhin noch einmal überprüfen?

� Zu Qualitätsmerkmal YZ ist ein neues Szenario erarbeitet worden. Welche Lösungsalter-nativen halten wir dagegen?

Tatsächlich stehen die betreffenden Dinge in Beziehung zueinander, wie exemplarisch in Bild 3.3 gezeigt. In der Architekturdokumentation sind die Zusammenhänge zwar idea-lerweise in Prosa oder stichpunkthaft beschrieben (siehe Vorlage zu Entscheidungen). Die Informationen sind aber gut über das ganze Dokument verstreut. Deshalb kann man leicht den Überblick verlieren. Es besteht die Gefahr, Zusammenhänge zu übersehen. Daher bietet sich an, die betreffenden Beziehungen zu verdichten und näher zueinander zu bringen. Eine gute Möglichkeit, Verknüpfungen überblicksartig darzustellen, sind Kreuztabellen.

«entscheidung»01. Auf welcher Ablaufumgebung

basiert der Server?

«qualitätsziel»Zuverlässigkeit

«qualitätsziel»Wartbarkeit

«randbedingung»Betriebssystem Linux für

Server «randbedingung»Einsatz von Open Source

«randbedingung»Skills der Mitarbeiter

«szenario»8. Während des Spielbetriebes fällt ein Server

aus. Laufende Partien können ohne Beeinträchtigung zu Ende gespielt werden.

«verfeinert»

«adressiert»«adressiert»

«berücksichtigt»

«berücksichtigt»

«berücksichtigt»

Bild 3.3 Ausschnittartige Zusammenhänge rund um eine Fragestellung

3.3.2■ Kreuztabellen

Eine „normale“ Tabelle (wie z. B. in einer relationalen Datenbank) enthält Spaltenüberschrif-ten und darunter Datensätze als Zeilen, deren Zellen jeweils einen Wert für das Merkmal der entsprechende Spalte angeben. Im Gegensatz dazu enthält eine Kreuztabelle sowohl Spalten- als auch Zeilenüberschriften, diese enthalten jeweils die Ausprägungen eines Merk-mals (z. B. die verschiedenen Qualitätsziele). Die Tabellenzellen werden als Schnittpunkte (Kreuzpunkte) der beiden Merkmale gelesen.

72 3 Entscheidungen treffen und festhalten

Als Merkmale kommen in unserem Fall Fragestellungen, Entscheidungen, Anforderungen und Einflüsse aller Art in Frage, konkret etwa: � Architekturentscheidungen, einzelne Alternativen � User Stories � Qualitätsmerkmale, Qualitätsziele, Qualitätsszenarien � Randbedingungen � Technische Risiken

Für eine konkrete Ausprägung einer Kreuztabelle entscheiden Sie sich für zwei Merkmale und stellen diese als Zeilen und Spalten einer Tabelle dar. Im einfachsten Fall verknüpft ein X in der bestimmten Zelle die betreffenden Ausprägungen der Merkmale miteinander. Korrekt gepflegt, verhilft die Tabelle sehr schnell zu Antworten auf Fragen wie diese: � Welche Entscheidungen wurden durch die Skills unserer Mitarbeiter beeinflusst? � Wie beeinflussen sich Architekturentscheidungen untereinander? � Bei welchen Qualitätsmerkmalen mussten wir Kompromisse eingehen? � Zu welchen Qualitätszielen haben wir (noch) keine Qualitätsszenarien?

3.3.3■ Fallbeispiel: Einflüsse „immer­nur­schach.de“

Zur Illustration zeigt Tabelle 3.1, welche Qualitätsziele von „immer-nur-schach.de“ (vgl. Kapitel 2.5.3) durch die verschiedenen Fragestellungen (vgl. Kapitel 3.2.4) besonders adressiert werden.

Tabelle 3.1 Welche Fragestellungen adressieren vorrangig welche Qualitätsziele?

Benutzbar-keit

Zuverlässig-keit

Wartbar-keit

1. Auf welcher Ablaufumgebung basiert der Server? X X2. Wo wird der Zustand einer laufenden Online­

Partie gehalten?X X

3. Welches Programmiermodell/Framework wird für den Server verwendet?

X

4. Wo werden Daten persistiert? X5. Wie werden Daten persistiert? X X6. Wie wird die Web­Applikationen realisiert? X X7. Wie interagieren Clients und Server bei Partien

miteinander?X X

8. Wird für alle Benutzergruppen die gleiche Client­technologie verwendet?

X X

9. Wie wird die Forenfunktionalität abgebildet? X10. Wie wird die Internet­Werbung realisiert? X

3.3 Einflussfaktoren auf Entscheidungen 73

3.3.4■ Tipps zur Anfertigung von Kreuztabellen

Einfache Kreuztabellen wie Tabelle 3.1 stellen lediglich eine Beziehung zwischen zwei Merkmalen dar. Für verschiedene Fragestellungen sind dann auch verschiedene Tabellen zu erstellen und zu pflegen. Alternativ dazu können Kreuztabellen mehrere Merkmale als Zeilen oder Spalten aufnehmen, z. B. Qualitätsziele und Randbedingungen in zwei Blöcken nebeneinander oder untereinander. Auch mehrdimensionale Darstellungen sind durch ge-eignete Schachtelung der Zeilen und Spalten möglich.Kreuztabellen mit mehr als zwei Merkmalen werden schnell sehr groß und somit für über-blicksartige Dokumentation unhandlich. Generell sind sie zu allererst ein Arbeitsmittel, in den Architekturüberblick sollten Sie nur die aufnehmen, die ein besonders spannendes Zu-sammenwirken beschreiben, ggf. in vereinfachter Form. In Tabelle 3.1 habe ich entsprechend die geforderten Qualitätsmerkmale und nicht die Szenarien gewählt.

Weitere Informationen in einer TabelleAnstelle eines Kreuzes können Sie in die Zelle auch Werte aufnehmen, etwa eine Priorisie-rung oder Gewichtung. In der Statistik werden solche Tabellen benutzt, um Informationen zusammenzufassen und zu verdichten.Je nachdem, mit welchen Werkzeugen Sie die Kreuztabellen erstellen und pflegen, können solche Werte die Arbeit mit ihnen verbessern, z. B. durch die Möglichkeit, zu filtern oder zu sortieren. Auch das Aufnehmen eines detaillierteren oder weiteren Einflusses in die Tabellenzellen ist denkbar. Anstatt der Kreuze in Tabelle 3.1 können Sie auch besonders relevante Qualitätsszenarien zu dem Thema in die Zellen aufnehmen. Beim Bewerten von Lösungsalternativen gegen Kriterien sind Stichpunkte in der Tabelle oft aussagekräftiger als (++), (+), (–) … allein.

WerkzeugfrageIm Grunde ein Vorgriff auf das Werkzeugkapitel, aber die Frage liegt natürlich auf der Hand: Wie erstellen Sie Kreuztabellen effizient, insbesondere wenn Sie mehrere Zusammenhänge darstellen oder die Zusammenhänge unterschiedlich detailliert oder gefiltert haben wollen?Die naheliegende Werkzeugwahl für Kreuztabellen sind Tabellenkalkulationen wie z. B. Excel. Wenn die gleichen Informationstypen unterschiedlich miteinander verknüpft werden sollen, ist es attraktiv, die Elemente und Beziehungen untereinander als Graph in einem Modell zu speichern und die Kreuztabellen daraus zu generieren. Bild 3.4 zeigt als Beispiel das UML-Werkzeug Enterprise Architect6, das eine solche Funktionalität bietet. Modelliert wurden die Beziehungen in Diagrammen wie z. B. Bild 3.3 auf der nächsten Seite.

6 Sparx Systems, http://www.sparxsystems.com

74 3 Entscheidungen treffen und festhalten

Bild 3.4 Beziehungen zwischen Modellelementen in einem UML­Werkzeug

Schematische Darstellungen aus KreuztabellenAuch der umgekehrte Weg, also das Ableiten einer graphischen Darstellung aus einer Kreuz-tabelle ist denkbar. Ein Beispiel haben Sie in Bild 3.2 gesehen, ich habe es mit Graphviz7 erstellt.

■■ 3.4■ Kompakte Darstellung der Lösungsstrategie

Mit der Mindmap aus Bild 3.1 haben Sie eine Struktur zum nachvollziehbaren Festhalten einer einzelnen Architekturentscheidung kennengelernt. Zusätzlich helfen grafische Darstellungen und Tabellen dabei, die Zusammenhänge zwischen mehreren Fragestellungen (Beispiel siehe Bild 3.2) oder auch zwischen Fragestellungen und ihren relevanten Einflüssen (Beispiele siehe Bild 3.3 und Tabelle 3.1) aufzuzeigen. Zum Abschluss dieses Kapitels stelle ich Ihnen noch ein Dokumentationsmittel vor, das effizient aufs Ganze blickt.

7 http://www.graphviz.org, siehe auch Kapitel 7

3.4 Kompakte Darstellung der Lösungsstrategie 75

3.4.1■ Softwarearchitektur auf einem Bierdeckel?

Die unliebsame jährliche Einkommenssteuererklärung manifestiert sich in einem grau-grünen Papierungetüm, ihr Ausfüllen lässt in Deutschland so manchen verzweifeln. Der CDU-Politiker Friedrich Merz machte 2003 mit einem radikalen Konzept zur Steuerreform auf sich aufmerksam: Die Steuererklärung sollte demnach auf einen Bierdeckel passen. Ein verlockendes Bild, leider nicht von Erfolg gekrönt.Können wir eine Softwarearchitektur auf einem Bierdeckel erklären? Als Idealbild hatte ich in Kapitel 2 einen Architekturüberblick inklusive Inhaltsverzeichnis, Abbildungen usw. auf weniger als 30 Seiten angestrebt. Die Lösungsstrategie für ein Softwaresystem lässt sich jedoch noch weiter verdichten, sodass sie auf eine DIN-A4-Seite passt – oder auf ein bis zwei Folien.

„Eine Strategie (von griechisch strategós „Feldherr, Kommandant“) ist ein Plan zum systema-tischen Erreichen von Zielen …“ (Wikipedia)

3.4.2■ Lösungsstrategie (Dokumentationsmittel)

Eine besonders kompakte und wirkungsvolle Form zur Dokumentation und Kommunikation der Lösungsstrategie stellt die wichtigsten Anforderungen den Lösungsansätzen in einer Tabelle gegenüber, siehe Bild 3.5.

Bild 3.5  Schematische Darstellung einer Lösungsstrategie in Tabellenform, und Bezug zu einem Überblicksbild

Die linke Spalte enthält dabei die Qualitätsziele (oder auch Architekturziele) aus Kapitel 2. Für ein ausdrucksstarkes Ergebnis zahlt es sich hier aus, wenn Sie den Zielen prägnante Namen gegeben haben (z. B. „Intuitive Erlernbarkeit“ statt nur „Benutzbarkeit“). In der rechten Spalte ordnen Sie den Zielen die wichtigsten Lösungsansätze Ihrer Architektur zu, die aus Ihrer Sicht der Erreichung der Ziele dienen. Als Erstes sind hier die Architekturentscheidungen zu nennen. Tabelle 3.2 listet darüber hinaus weitere mögliche Kategorien auf und illustriert sie mit Beispielen. Die einzelnen Ansätze nennen Sie in der Tabelle nur schlagwortartig, beispielsweise „JPA/Hibernate als Persistenzframework“. Auf detaillierte Informationen (z. B. die ausführliche Darstellung einer Architekturentscheidung inklusive betrachteter Alternativen, das ausgearbeitete Konzept etc.) verweisen Sie lediglich.8

8 Wie sich die Lösungsstrategie in eine Architekturbeschreibung nach arc42 einbettet, erläutere ich in Kapitel 4.3.

76 3 Entscheidungen treffen und festhalten

Tabelle 3.2 Mögliche Architekturansätze in einer Lösungsstrategie

Kategorie Beispiel (und dazu passendes Qualitätsziel)Entscheidungen Verwendung eines Application Server Clusters (hohe Ausfallsicherheit)(Architektur­)stile Microservices (schnelle Adaption neuer technologischer Trends)(Architektur­)muster Schichtenarchitektur (leichte Austauschbarkeit des Clients oder ein­

fache Portierung der Lösung)(Architektur­)prinzipien Bevorzuge Standards vor proprietären Lösungen (niedrige Wartungs­

aufwände)Konzepte Caching­Konzept (Effizienz, gute Antwortzeiten)Vorgehen User centered design (intuitive Benutzbarkeit)

Ansätze wie in Tabelle 3.2 wählen Sie und Ihr Team typischerweise aus – Sie entscheiden. In Einzelfällen können Sie aber auch Randbedingungen als „Argumente“ für Ihre Architek-tur anführen. Wenn beispielsweise Technologien vorgegeben sind, die gleichzeitig gut zu den Zielen passen, können Sie diese in der rechten Seite ebenfalls nennen. Ein einzelner Lösungsansatz kann mitunter mehreren Zielen dienlich sein. Sie listen ihn in der rechten Spalte dann einfach mehrmals auf.Um Interessierten einen Einstieg in Ihre bereits entstandene Dokumentation zu geben, können Sie die Lösungsstrategie als eine Art Zusammenschau nachdokumentieren. Besser noch beginnen Sie aber früh mit einer ersten Fassung, um Sicherheit im Architekturentwurf zu gewinnen (siehe auch Kapitel 3.4.5) und der Verwässerung wichtiger Architekturansätze entgegenzuwirken.

Steckbrief: Dokumentationsmittel „Lösungsstrategie“Synonym: Architekturvision

Zweck:Stark verdichteter Architekturüberblick, Gegenüberstellung der wichtigsten Ziele und Lösungsansätze der Architektur

Form:Tabelle mit zwei Spalten, je Zeile links ein Qualitätsziel, rechts dazu stichwortartig die passenden Lösungsansätze der Architektur; ggf. ergänzt um ein Überblicksbild

Checkliste für den Inhalt: � Enthält die Tabelle sämtliche Qualitätsziele? � Ist zu jedem Qualitätsziel mindestens ein Architekturansatz angegeben? � Sind die Lösungsansätze kurz und knapp benannt? � Ist es schlüssig, dass die Ansätze positiv zu den Zielen beitragen? � Ist bei Entscheidungen und Konzepten auf Begründungen bzw. Ausarbeitungen verwiesen?

� Liegen die Lösungsansätze tatsächlich in der Architektur vor (und sind es nicht nur vage Möglichkeiten)?

3.4 Kompakte Darstellung der Lösungsstrategie 77

Weiterführende Literatur:Die Vorgehensmuster in [Toth2015], speziell das Muster „Gerade genug Architek-tur vorweg“

Ablageort arc42:Abschnitt 4: „Lösungsstrategie“

3.4.3■ Fallbeispiel: Lösungsstrategie „DokChess“

Die folgende Tabelle stellt die Qualitätsziele von DokChess den passenden Architekturan-sätzen der Lösung gegenüber.

Tabelle 3.3 Lösungsstrategie DokChess

Qualitätsziel Dem zuträgliche Ansätze in der ArchitekturZugängliches Beispiel (Analysierbarkeit)

� Architekturüberblick gegliedert nach arc42 � Explizites, objektorientiertes Domänenmodell � Modul­, Klassen­ und Methodennamen in Deutsch, um englische Schachbegriffe zu vermeiden

� Ausführliche Dokumentation der öffentlichen Schnittstellen in javadocEinladende Experimentier­plattform (Änderbarkeit)

� Verbreitete Programmiersprache Java � Schnittstellen für Kernabstraktionen (z. B. Stellungsbewertung, Spielregeln)

� Unveränderliche Objekte (Stellung, Zug, …) erleichtern Implemen­tierung vieler Algorithmen

� „Zusammenstecken“ der Bestandteile mit Dependency Injection führt zu Austauschbarkeit

� Hohe Testabdeckung als SicherheitsnetzBestehende Frontends nutzen (Interoperabilität)

� Verwendung des verbreiteten Kommunikationsprotokolls xboard � Einsatz des portablen Java

Attraktive Spielstärke (Attraktivität)

� Integration von Eröffnungsbibliotheken � Implementierung des Minimax­Algorithmus und einer geeigneter Stellungsbewertung

� Integrationstests mit Schachaufgaben für taktische Motive und Mattsituationen

Schnelles Antworten auf Züge (Effizienz)

� Reactive Extensions für nebenläufige Berechnung mit neu gefundenen besseren Zügen als Events

� Optimierung des Minimax durch Alpha­Beta­Suche � Effiziente Implementierung des Domänenmodells � Integrationstests mit Zeitvorgaben

78 3 Entscheidungen treffen und festhalten

In Kapitel 9.4 ist die Lösungsstrategie weiter erläutert und mit Verweisen auf die genannten Konzepte und detaillierte Begründungen für zentrale Entscheidungen versehen.

3.4.4■ Als Ergänzung: ein Überblicksbild

Die Lösungsstrategie kann das Anfertigen eines Überblicksbilds Ihrer Architektur leiten. Sie fertigen eine Skizze an, in der Sie die einzelnen Ansätze verorten. In Bild 3.5 ist dieser Schritt rechts angedeutet. Nicht immer findet jeder Ansatz einen genauen Platz, aber gerade in Schichtenarchitekturen können Sie Bibliotheken, Frameworks oder Kommunikationspro-tokolle oft gut lokalisieren.Kapitel 9.4 enthält als Beispiel auch ein schematisches Überblicksbild, in dem einzelne Architekturansätze von DokChess eingezeichnet sind.

3.4.5■ Eine Architekturbewertung auf dem Bierdeckel

Die Lösungsstrategie in der gezeigten Form ist nicht nur exzellent geeignet, um die grund-legendsten Aspekte Ihrer Architektur zu nennen und dabei gleichzeitig zu motivieren. Sie hilft auch während des Entwurfs der Architektur dabei, Lücken und Ungereimtheiten aufzudecken. Wenn Sie zu einem Architekturziel keine passenden Lösungsansätze in der Architektur identifizieren, ist da noch etwas zu tun. Und wenn Sie umgekehrt einen zentra-len Aspekt der Architektur keinem Ziel zuordnen können, sollten Sie ihn hinterfragen. Im Grunde stellt die Tabelle eine besonders schlanke Form der Architekturbewertung dar. Passt die Lösung zur Zielsetzung?

Kernaussage dieses KapitelsBeim Dokumentieren einer Architekturentscheidung ist der Lösungsweg mindes-tens so interessant wie die getroffene Entscheidung selbst. Ihre Annahmen gehö-ren genauso dazu wie verworfene Alternativen. Sie lassen sich aus der realisierten Lösung später schwer ablesen, ebenso Ihre Begründung. Halten Sie zentrale Ent-scheidungen bereits im Entstehen fest, und wählen Sie eine Form, in der Sie und Ihre Leser den Überblick behalten!

Stichwortverzeichnis

Symbole4+1 Sichten (RUP) 132

AAbgrenzung

– Architekturdokumentation 10, 256 – Kontext siehe Systemkontext

Abhängigkeiten 96Ablaufbeschreibung siehe LaufzeitsichtADM (Architecture Development Method) 91Agiles Manifest 6Agilität 5, 90Akteur 29Aktivitätsdiagramm 122

– Beispiel 124Analysemuster 135Analysierbarkeit 43

– Beispiele 44, 247Änderbarkeit 43

– Beispiele 44, 247Anforderungserhebung siehe Requirements

EngineeringAnnahmen 63Anpassbarkeit 43

– Beispiele 247AOP siehe aspektorientierte ProgrammierungAPI siehe SchnittstellenbeschreibungApplikationsserver 143arc42 9, 82, 266

– Alternativen 87 – Beispiel 211 – Mapping zum Buch 86 – Struktur 83 – im UML-Modell 176 – im Wiki 173

Architecture Development Method 91Architektur

– Definitionen 17, 95, 266 – Vorgehen 18

Architekturbewertung 41, 47, 193Architekturbrezel 19

Architekturdokumentation 7, 266 – Gliederung 80 – Ziele 7

Architekturentscheidung 18, 62, 198, 265 – Beispiele 64, 66, 242 – Einflussfaktoren 70 – typische Fragestellungen 65 – Steckbrief 69 – Überschrift 66 – Vorlage 62 – Zusammenhänge 71

Architektur-Framework 90Architekturmuster 135, 141Architekturstil 134Architekturtapete 95Architekturüberblick 23, 152, 188

– Beispiel 211 – Gliederung 80 – Präsentation 92

Artefakt (UML) 127AsciiDoc 168aspektorientierte Programmierung 144, 205ATAM 41Attraktivität 43

– Beispiele 44, 247Aufwand 7, 253Ausführungssicht siehe Laufzeitsicht

BBaustein 100Bausteinsicht 97, 198, 265

– Beispiele 98, 117, 223 – Steckbrief 104 – in UML 101

Bebauungsplan 207Begriffsklärung siehe GlossarBenutzbarkeit 42

– Beispiele 44, 46, 247Benutzer 29Betriebsaspekte 126, 142Bewertung siehe Architekturbewertung

274 Stichwortverzeichnis

Bewertungsszenarien siehe QualitäzsszenarienBibliothek 143Bilder (in Dokumentation) 159Blackboard (Muster) 141Blackbox 96Blog 164Blue Print 85, 192, 209BPMN 121Buch

– Aufbau 12 – Feedback 14 – Übungsaufgaben siehe Übungsaufgaben – Webseite 14

Budget 36, 47 siehe auch RandbedingungenBugtracking 165, 196

CChecklisten siehe einzelne Steckbriefe

– bei Reviews 262Computerschach 14, 211

DDatenbank 32Datenformate 108Definition of Done 22Deployment siehe Verteilung

– Diagram siehe Verteilungsdiagramm – Unit 129 – View (RUP) 133

Design 18Design Patterns siehe EntwurfsmusterDiagramm 21 siehe auch Bilder, UMLDocBook 165, 168Doctator (Rolle) 22, 191, 258Dokumentation, Definition 9Dokumentationslandkarte 191Dokumentationsmittel 9, 268Dokumentenmanagement 170Doxygen 202Drucken 171Durchstich 19

EEffizienz 42

– Beispiele 44, 47, 247Einflussfaktoren 17, 70Engine siehe Schach-EngineEntscheidung siehe ArchitekturentscheidungEntwurfsmuster 135

– Beispiel 138Eventualfallplanung 58Extreme Programming 6

FFallbeispiele

– DokChess 25, 211 – immer-nur-schach.de 27 – Squeezebox 34

Feedback 262 – zum Buch 14

Fehlertoleranz 43 – Beispiel 247

Flipchart 163Fragenkataloge bei Reviews 262Fragestellung siehe ArchitekturentscheidungFramework 143, 208Fremdsystem 28, 65funktionale Anforderungen 18Funktionalität 42FURPS 42

GGebrauchstauglichkeit (von Dokumentation)

260gedruckte Dokumentation 171gesetzliche Bestimmungen 36

siehe auch RandbedingungenGlossar 59, 83, 198

– Beispiele 251, 265 – Steckbrief 60

grafisches Glossar 60 – Beispiel 88, 265

Graphviz 74, 167Gutachten siehe Review

HHardware-Vorgaben siehe Randbedingungenhistorisch gewachsen 4, 62, 192

IIDL 107IEEE 1028 259IEEE 1417 87Implementation View (RUP) 133Informationsquellen 195Infrastruktur 129Infrastruktursicht siehe VerteilungssichtInspektion 259Interoperabilität 43

– Beispiele 44, 47, 247Intranet 172ISO 9126 42ISO 25000 42ISO 42010 87

Stichwortverzeichnis 275

KKnoten (UML) 127Kommunikation 7, 190Kommunikationsprotokoll 29Komponentenbegriff 100Komponentendiagramm 96, 104

– Beispiele 98, 117, 229Komponentenmodell siehe BausteinsichtKompositionsstrukturdiagramm 104Kompromiss 19

– Beispiele 46, 48Konformität (von Dokumentation) 260Konsistenz 8, 115Kontextabgrenzung siehe SystemkontextKonventionen 39Konzepte 21 siehe auch Übergreifendes

KonzeptKonzernvorgaben 36

siehe auch RandbedingungenKreuztabelle 71

– Beispiele 72, 200, 204, 243Krisenmanagement 57

LLastenheft 89, 196LaTeX 165, 168Laufzeitsicht 120, 265

– Beispiele 124, 232 – Steckbrief 123

Laufzeitumgebung 126Legende 34Logical View (RUP) 133Logitech Media Server siehe SqueezeboxLösungsstrategie 74, 84

– Beispiel 220 – Steckbrief 76

MMake or buy 18, 68Markdown 165Messung 19Metrik 19, 203Mind Mapping 51, 164Mission Statement 24

siehe auch ProduktkartonModell 21, 114Moderationskarten 163Modul 100Muster 135, 141

– Beispiel 138

NNachvollziehbarkeit 8, 48, 61, 260nicht-funktionale Anforderungen 19

siehe auch Qualitätsmerkmale

OObjektdiagramm 123Open Unified Process 88Outsourcing 192

PPaketdiagramm 104Performance siehe EffizienzPersona 54, 198, 265

– Beispiele 55, 213 – Steckbrief 56

Pflichtenheft 89, 196Pinnwand 163Pipes & Filters (Muster) 141Podcast 172Portierbarkeit 43

– Beispiele 247Port (UML) 96PowerPoint 166Präsentationsprogramm 166Process View (RUP) 133Product Owner 48Produktkarton 24, 45, 197, 265

– Beispiele 27, 212 – Steckbrief 28

Programmiervorgaben siehe RandbedingungenProjektglossar siehe GlossarProjektmanagement 38, 53Prototyp 19Pseudocode 120

QQualitäten siehe QualitätsmerkmaleQualitätsbaum 50

– Beispiele 50, 247Qualitätsmerkmale 28, 42

– Kategorien 42Qualitätsszenarien 47, 165, 198, 265

– Beispiele 48, 248 – Bestandteile 47 – Kategorien 48 – Steckbrief 52

Qualitätsziele 43, 63, 197, 265 – Beispiele 44, 212 – Steckbrief 45

Quelltext 19, 195, 201querschnittliche Themen siehe Übergreifendes

Konzept

276 Stichwortverzeichnis

RRahmenbedingungen siehe RandbedingungenRandbedingungen 36, 47, 63, 197, 265

– Beispiele 38, 216 – Kategorien 39 – Steckbrief 41 – Vorlagen 39

Rational Unified Process 88, 132Referenzarchitektur 209Regeln für gute Dokumentation 184Rekonstruktion 201Repository 83, 172, 187Requirements Engineering 18, 38, 53Review 19, 258

– Meeting 262 – Typen 259 – Ziele 260

Richtlinien siehe Randbedingungen – für Architekturdokumentation 257

Risiken 19, 57, 63, 85, 198, 265 – Beispiele 57, 249 – Steckbrief 59

risikogetrieben 19Risikomanagement 53, 57Risikominderung 58Rollen

– Doctator siehe Doctator – Softwarearchitekt 21 – im Systemkontext 33

RUP siehe Rational Unified Process

SSchach-Engine 16, 212Schichten 116, 118, 141Schnittstellen 105

– Notation in UML 106Schnittstellenbeschreibung 108, 265

– Beispiel 110 – Steckbrief 112 – Vorlage 108

Screenshot 158Scrum 6, 22, 88Sequenzdiagramm 121

– Beispiel 232Sicherheit 43

– Beispiele 46, 47Sichten 95, 113, 198

– alternative Vorschläge 132 – in UML 114

Skills der Mitarbeiter 36 siehe auch Randbedingungen

Softsqueeze 35Softwarearchitekt (Rolle) 21

Softwarearchitektur siehe ArchitekturSoftwarequalität 42Software-Vorgaben siehe RandbedingungenSonarQube 204Squeezebox 35Stakeholder 43, 53

– Beispiel 213Standardnotation 160Stereotyp (UML) 29, 100Strukturierung 18, 96Struktursicht siehe BausteinsichtSubsystem 98Synonyme 59 siehe auch GlossarSystemidee siehe ProduktkartonSystemkontext 29, 197, 265

– Beispiele 30, 218 – Rollen 33 – Steckbrief 34 – technisch vs. fachlich 31

Systemkontextdiagramm 29Systemlandschaft 85, 206Szenarien siehe Qualitätsszenarien

TTabellenkalkulation 166Tagcloud 158

– Beispiele 99, 162Technische Risiken siehe RisikenTechnisches Konzept siehe Übergreifendes

KonzeptTest 19, 122Text (in Dokumentation) 158Textverarbeitung 165, 168TOGAF 90Tools siehe WerkzeugeTravel light 7

UÜbergreifendes Konzept 139, 199, 265

– in arc42 154 – Beispiele 146, 235 – Lösungsoptionen 142 – Steckbrief 152 – Themenauswahl 144 – Themenkandidaten 140 – Vorlage 150

Übungsaufgaben 14, 34, 46, 56, 70, 119, 132, 154, 205

UML 29, 114, 161 – Beziehungen 103 – als Repository 176, 187 – Tool 167, 179

Unified Process 88

Stichwortverzeichnis 277

Unternehmensarchitektur 90, 206Use Case 18Use-Case View (RUP) 133User Story 18, 26Utility Tree siehe Qualitätsbaum

VVersionsverwaltung 169, 187Verteilungsdiagramm 127

– Beispiele 132, 233Verteilungssicht 129, 265

– Beispiele 131, 233 – Steckbrief 130

Vier-Quadranten-Modell 148Virtueller Produktkarton siehe ProduktkartonVision 28 siehe auch ProduktkartonV-Modell XT 89Vorgaben siehe Randbedingungen

– für Architekturdokumentation 255, 257Vorgehen 18

– agil 5, 90 – beim Dokumentieren 183 – Dokumentieren im Nachhinein 192 – klassisch 88 – bei Reviews 261 – risikogetrieben 19

Vorgehensmodell 88Vorlage 257

– Architekturdokumentation 82 – Architekturentscheidung 62 – Architekturüberblick 82 – Präsentation 92 – Schnittstellenbeschreibung 108 – Übergreifendes Konzept 150

WWalkthrough 259Wartbarkeit 42

– Beispiele 44, 47, 247Webseite

– Buch 14 – Fallbeispiel DokChess 211

Werkzeuge 162, 256 – Auswahl 157 – zur Erstellung 162 – zur Kommunikation 170 – zur Rekonstruktion 201 – zur Verwaltung 168

Werkzeugkette 22, 179Whiteboard 163, 198Whitebox 96Wiki 2, 22, 164, 172, 179

– Produktauswahl 176 – als Repository 173, 187

Word 165, 168Wortschatz siehe GlossarWSDL 107

ZZeichenprogramm 166Zeitplan 36, 47 siehe auch RandbedingungenZerlegung 96Zielgruppen 183, 256Zielsetzung 23Zielumgebung 129zugekaufte Komponente 32Zustandsautomat siehe ZustandsdiagrammZustandsdiagramm 122

– Beispiel 124Zuverlässigkeit 42

– Beispiele 44, 247