Kleines Einmaleins der Architekturdokumentation. Teil 1: Einflüsse und Entscheidungen Historisch gewachsen?

Transkript

1 Kleines Einmaleins der Architekturdokumentation. Teil 1: Einflüsse und Entscheidungen Historisch gewachsen? Softwarearchitektur ist die Summe fundamentaler Entscheidungen. Halten Sie zentrale Einflüsse und Ideen fest, anstatt sie zu vergessen. Gelangen Sie so zu einer nachvollziehbaren Lösung! Auf einen Blick Stefan Zörner arbeitet als Trainer und Berater bei oose in Hamburg. Ganz besonders interessiert ihn, wie sich Softwareentwürfe und -ideen effektiv festhalten lassen. Sie erreichen ihn über Inhalt Ziele der Dokumentation von Softwarearchitektur. Regeln für gute Dokumentation. Beispiel DokuChess. Die Strukturvorlage arc42. Serie 1. Einflüsse und Entscheidungen. 2. Sichten, Werkzeuge und Vorgehen. dnpcode A1209ArchiDoku W arum habt ihr das so gemacht? Würde man das nicht eigentlich besser so machen? Haben Sie schon einmal an einem Entwicklungsprojekt gearbeitet, zu dem im weiteren Verlauf ein neues Teammitglied hinzugekommen ist? Oder waren Sie selber einmal in einem Vorhaben der Neue? Dann kennen Sie die Situation. Neue Mitarbeiter stellen viele Fragen. Nachdem sie ihren Platz gefunden haben und arbeitsfähig geworden sind, sehen diese zum Beispiel so aus: Ich finde mich im Quelltext nicht zurecht. Wo finde ich X? Warum verwendet ihr Y? Aus welchem Grund ist Aspekt Z hier so und da anders gelöst? Könnten Sie diese Fragen immer beantworten? Das Wachsen von Teams offenbart in vielen Vorhaben Wissenslücken. Deutlich werden diese durch die Antworten, die Neue auf ihre Fragen erhalten (oder eben nicht erhalten). Der Klassiker in diesem Zusammenhang: Historisch gewachsen. Sicher möchten Sie auf Fragen neuer Mitarbeiter bessere Antworten parat haben. Wirkungsvolle Dokumentation unterstützt Sie bei dieser Kommunikation. Sie gestaltet die Einarbeitung neuer Mitarbeiter weniger steinig und hilft ihnen dabei, dass Lösungen anforderungsgerecht (gut genug) gelingen und einheitlich (gleiche Probleme werden gleich gelöst) bleiben. Kurz: Die Architektur verwässert nicht. Sieben Regeln für gute Dokumentation Paul Clements und seine Mitautoren stellen in ihrem Buch Documenting Software Architectures [1] die folgenden sieben Regeln für gute (im Englischen wörtlich sound ) Dokumentation an den Anfang. 1. Schreibe die Dokumentation aus der Sicht des Lesers. 2. Vermeide unnötige Wiederholungen. 3. Vermeide Mehrdeutigkeit. 3a. Erkläre deine Notation. 4. Verwende eine Standardstrukturierung. 5. Halte Begründungen fest. 6. Halte die Dokumentation aktuell, aber nicht zu aktuell. 7. Überprüfe die Dokumentation auf Gebrauchstauglichkeit. Dieser zweiteilige Artikel macht einige dieser Regeln konkret erlebbar, der vorliegende erste Teil vor allem die Regeln Nummer 4 und 5. Softwarearchitektur Worum genau geht es, wenn hier von Architektur die Rede ist? Es gibt nicht die eine, allgemein akzeptierte Definition für Softwarearchitektur. Stattdessen gibt es in der Literatur eine unüberschaubare Menge solcher Definitionen. Viele betonen die Strukturierung eines Softwaresystems in Bestandteile (zum Beispiel Komponenten) und wie diese Teile zusammenhängen. Oft schwingt mit, dass es sich bei Architektur um etwas Fundamentales, im Nachhinein schwer Änderbares handelt. In der Praxis hingegen funktioniert anstelle einer Definition eine simple Formel verblüffend gut: Architektur ist die Summe der zentralen Entscheidungen, die im weiteren Verlauf nur schwer zurückzunehmen sind. Der Vorteil: Der Ansatz mit Architekturentscheidungen ist universell, die Fragestellungen können sowohl die Strukturierung des Systems als auch eine Technologieauswahl oder Make-or-Buy-Entscheidungen betreffen. Somit passt diese Idee von Architektur auch gut zu den Fragestellungen neuer Mitarbeiter. Wer die Architektur erklären will, fokussiert auf die zentralen Fragestellungen und wie er (oder sein Team) sich entschieden hat, um Anforderungen zu erfüllen und Ziele zu erreichen. Drei Ziele für Dokumentation Dieses Verständnis von Softwarearchitektur gibt eine gute Orientierung, was festzuhalten wäre. Nun gehört Dokumentieren aber nicht unbedingt zu den Lieblingsbeschäftigungen von Entwicklern. Dokumentation ist in vielen Projekten ein Fremdwort. Schaut man im Fremdwörterlexikon des Duden nach, liest man: Do ku men ta ti on [...zio n] [lat.] die; -, -en: 1. a) Zusammenstellung u. Ordnung von Dokumenten und Materialien jeder Art, durch die das Benutzen und Auswerten ermöglicht oder erleichtert wird... Diese Definition trifft die Intention dieser Artikelserie überraschend gut: Sie erhalten praxistaugliche Vorschläge für Bestandteile einer Dokumentation sowie Hinweise, wie Sie diese Inhalte geeignet zusammenstellen. Es geht um das Festhalten von Intentionen und Überlegungen, die nach einem halben Jahr in Vergessenheit geraten würden und nicht aus dem Quell

2 [Abb. 2] Virtueller Produktkarton für DokChess. Produktkarton DokChess [Abb. 1] Schach-Engine, eingebunden in ein grafisches Frontend (Arena). text wiederherstellbar wären. Dokumentation ist kein Selbstzweck, sie unterstützt Kommunikation, erleichtert also das Benutzen der Architektur. Wirkungsvolle Architekturdokumentation kann dabei dreierlei leisten: beim Entwurf der Architektur unterstützen, die Umsetzung und Weiterentwicklung des Systems leiten, die Architektur nachvollziehbar und bewertbar machen. Klären Sie innerhalb Ihres Teams zunächst die Ziele, die Sie mit dem Festhalten Ihrer Architektur verfolgen (es müssen nicht alle drei sein), und identifizieren Sie die Zielgruppe(n) der Dokumentation (lesen Sie dazu auch den Kasten Sieben Regeln für gute Dokumentation). Fallbeispiel Schach-Engine Im Folgenden illustriert ein Beispielsystem zentrale Bestandteile einer Architekturdokumentation. Konkret geht es um eine Schach-Engine, also um ein Programm, das Schach spielt (Abbildung 1). Diese Systemidee zu vermitteln ist Ihr erstes Dokumentationsergebnis. Stellen Sie sich dazu einen Karton vor, in dem Ihre Software verkauft wird. Auf dem Karton stehen die zentralen Features, es wird erklärt, wozu das System da ist. Der Kasten Produktkarton DokChess zeigt die Systemidee der Schach- Engine. Ein Beispiel für den DokChess- Karton ist in Abbildung 2 zu sehen. Aus Architektursicht ist es entscheidend, bereits hier auch die nicht-funktionalen Anforderungen anzusprechen, denn diese beeinflussen Architekturentscheidungen besonders stark. Im Falle der Schach-Engine sind dies vor allem Erweiterbarkeit und Effizienz. Um einem neuen Mitarbeiter einen guten Einstieg in ein System zu geben, ist neben der Systemidee eine Kontextbetrachtung unerlässlich. Sie grenzt ab, wofür das System verantwortlich ist und wofür nicht. Wer sind die Benutzer des Systems? Mit welchen Fremdsystemen interagiert es? Abbildung 3 visualisiert das Umfeld des zu beschreibenden Systems, indem sie die Interaktionspartner darum versammelt. Zusätzlich zum Diagramm halten Sie für Ihr System für jeden Benutzertyp und jedes Fremdsystem noch in ein bis zwei Sätzen fest, warum Ihr System mit ihm interagiert, welche Rolle der Beteiligte also für Ihr System spielt. Hier im Artikel entfallen die Beschreibungen für das DokChess-Beispiel aus Platzgründen, Inhalte hierzu finden Sie auf [2]. Einflussfaktoren Architektur entwerfen heißt Entscheidungen treffen. Eine Kontextbetrachtung entpuppt sich dabei als vorzüglicher Generator für erste Fragestellungen. Was für Oberflächen erhalten die Benutzer? Wie binden wir Fremdsysteme an? Hier sind Technologien, Produkte, Protokolle auszuwählen. Die Entscheidung für eine bestimmte Alternative wird durch verschiedene Faktoren beeinflusst. Diese zusammenzutragen und zu berücksichtigen ist für gute Entscheidungen unerlässlich. Was ist DokChess? DokChess ist eine voll funktionsfähige Schach-Engine. Sie dient als einfach zugängliches und zugleich attraktives Fallbeispiel für Architekturentwurf, -bewertung und -dokumentation. Der verständliche Aufbau lädt zum Experimentieren und zum Erweitern der Engine ein. Ziel ist nicht die höchstmögliche Spielstärke dennoch gelingen Partien, die Gelegenheitsspielern Freude bereiten. Wesentliche Features Vollständige Implementierung der FIDE- Schachregeln. Unterstützt das Spiel gegen menschliche Gegner und andere Schach-Engines. Beherrscht zentrale taktische Ideen, beispielsweise Gabel und Spieß. Integration mit modernen grafischen Schach-Frontends. Sie darüber hinaus geeignet festzuhalten ist der Schlüssel für nachvollziehbare Architekturen. Denn während sich die Entscheidung selbst oft direkt in der Lösung widerspiegelt (zum Beispiel: Wir benutzen Framework XY), gerät der Weg dorthin schnell in Vergessenheit. Einflussfaktoren lassen sich unterscheiden in: Randbedingungen, technische Risiken, Qualitätsanforderungen. Randbedingungen geben den Rahmen für Entscheidungen vor. Hierzu zählen organisatorische Aspekte wie Zeitrahmen, Budget oder die Fähigkeiten der beteiligten Mitarbeiter (Skills). Auch technische Vorgaben wie die zu verwendende Programmiersprache, die Zielhardware oder die Laufzeitumgebung können dazu zäh

3 Kleines Einmaleins der Architekturdokumentation [Abb. 3] Systemkontext. Mit wem spielt DokChess zusammen? [Abb. 4] Gliederung, um eine Entscheidung zu treffen und festzuhalten. len. Wieso können? Während beispielsweise das eine Projekt die Programmiersprache frei auswählen darf (und dabei in der Regel eine Architekturentscheidung trifft), muss ein anderes Vorhaben sich im selben Punkt vielleicht an eine Konzernvorgabe halten (Randbedingung). Randbedingungen engen den Lösungsraum ein, sie schließen Alternativen aus. Eine ähnliche Wirkung können technische Risiken bei Entscheidungen haben. Ist eine Alternative mit zu hoher Unsicherheit behaftet (zum Beispiel Technologie im Team nicht bekannt, nicht ausgereift, Gefahr eines Vendor-Lock-in), kann das ein guter Grund sein, sie aus der engeren Wahl zu nehmen. Qualitätsanforderungen schließlich lassen sich auf allgemeine Qualitätsmerkmale zurückführen. Das sind Eigenschaften einer Software, die über die reine Funktionalität hinausgehen. Im Deutschen enden viele dieser Merkmale auf -heit oder -keit, etwa Benutzbarkeit, Sicherheit, Wartbarkeit. Im Kontext einer konkreten Entscheidung wirken sich Alternativen unterschiedlich auf Qualitätsmerkmale aus. Oftmals stehen diese wechselseitig in Beziehung zueinander. Was gut ist für die Sicherheit, kann schlecht sein für die Benutzbarkeit. Performance-Optimierungen wirken sich oft negativ auf die Wartbarkeit und Portierbarkeit aus. Das zeigt sich bei DokChess insbesondere in der Wahl der Datenstrukturen und Algorithmen. Die Spielsituation auf dem Brett beispielsweise lässt sich durch ein 8x8-Array repräsentieren, das Figuren (Farbe und Typ, zum Beispiel weißer Bauer) geeignet speichert. Alternativ könnten auch 64-Bit- Variablen (long) verwendet werden; pro Figurenart eine Variable, die Bits repräsentieren die 64 Felder. Für die weißen Bauern werden genau die Bits gesetzt, wo im Moment eine entsprechende Figur steht. Eine weitere Long-Variable wird für die schwarzen Bauern verwendet, insgesamt braucht man zwölf Variablen (es gibt im Schach sechs verschiedene Figuren). Ein solcher Bitboard-Ansatz [3] erlaubt sehr effiziente Berechnungen. Die freien Felder auf dem Brett etwa sind durch eine logische Oder-Verknüpfung der Werte schnell ermittelt. Auf der anderen Seite ist die Bestimmung gültiger Züge mit Bit- Operationen weitaus komplizierter als bei einem zweidimensionalen Array, wo man direkt mit der Koordinatendarstellung arbeiten kann. Ein typischer Trade-off also zwischen Effizienz und Einfachheit, wobei Letztere auf die Wartbarkeit wirkt. Während Randbedingungen durch die Architektur einzuhalten sind, werden Qualitätsmerkmale durch Entscheidungen ausbalanciert. Sind die Qualitätsziele im Rahmen des Entwurfs unbekannt, erreicht das Team sie bestenfalls zufällig (accidental architecture) und verliert gewonnene Eigenschaften im Rahmen der Weiterentwicklung schnell. Entscheidungen treffen Wie finden Sie nun auf Grundlage der Einflussfaktoren Antworten auf zentrale Fragestellungen, und wie halten Sie die Entscheidungen fest? In der Praxis haben sich hierzu einfache Templates bewährt. Für jede zentrale Entscheidung fragen sie die gleichen Dinge ab und stellen so alle Architekturentscheidungen der Lösung gleichförmig dar (siehe Regel 4: Verwende eine Standardstrukturierung). Abbildung 4 zeigt hierzu einen konkreten Vorschlag (Quelle: [4]), der Ihnen sowohl Orientierung beim Bearbeiten einer Entscheidung gibt als auch eine Struktur zum Festhalten liefert die Hauptäste der Mindmap dienen dann als Überschriften. An den einzelnen Ästen sind Fragen angehängt, die Sie in Ihre Vorlage mit aufnehmen können. Sie müssen diese Fragen aber nicht sklavisch beantworten. Vielmehr sollen diese Sie und Ihr Team bei einer konkreten Architekturentscheidung, etwa in einem Workshop, leiten, anregen und unterstützen. Fragestellung und Annahmen Die Inhalte der Mindmap-Äste wurden zum Teil bereits angesprochen. Zwei Punkte verdienen noch besondere Aufmerksamkeit: Fragestellung und Annahmen. Entscheidungen im Projekt gibt es viele. Stellen Sie überzeugend dar, warum die hier betrachtete Fragestellung tatsächlich eine Architekturentscheidung ist. Der Kasten Spannende Fragen zu DokChess enthält einige Kandidaten zur Illustration. Die beschriebenen Einflussfaktoren grenzen die Fragestellung nicht völlig ein, sondern lassen Ihnen Entscheidungsspielraum. Sie treffen Annahmen, welche

4 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. Annahmen zählen zu den Dingen, die im Nachhinein beinahe unmöglich zu rekonstruieren sind. Halten Sie sie fest! Bei der Wahl geeigneter Werkzeuge sollten Sie auf jeden Fall den Kommunikationsaspekt im Auge behalten. Architekturentscheidungen sollte jeder im Team kennen und erläutern können. Wenn Sie und Ihr Team sich entscheiden, bestimmte Aspekte in Zukunft einheitlich zu lösen, müssen Sie das in die Breite tragen. Deshalb sind Wikis zum Erarbeiten und Festhalten von Architekturaspekten sehr beliebt. Sie haben die Kollaboration direkt eingebaut. Die Struktur aus Abbildung 4 lässt sich im Wiki gut als Template hinterlegen, entsprechende Seiten taggen Sie mit Entscheidung. Ich habe auch schon Teams gesehen, die innerhalb ihres Projekts einen Blog benutzt haben, um Entscheidungen zu dokumentieren. Die Wahl des Tools ist allerdings weitaus weniger wichtig als das Spannende Fragen zu DokChess Im Rahmen der Realisierung der Schach-Engine DokChess stellte sich eine ganze Reihe von Fragen. Hier eine Auswahl zur Illustration: 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? Auf der DokChess-Seite [2] finden Sie Antworten auf diese Fragen, insbesondere sind zwei besonders zentrale in der Gliederungsstruktur aus Abbildung 4 festgehalten. Bewusstsein innerhalb des Teams, dass bestimmte Entscheidungen nachvollziehbar festgehalten werden müssen. Ordnen und Abheften Sie haben eine Reihe zentraler Bestandteile einer Architekturdokumentation kennengelernt. Mit Produktkarton, Einflussfaktoren, Architekturentscheidungen und so weiter sammeln sich nach und nach Dinge an, die Sie in Ordnung halten müssen. Das betrifft sowohl die Verwahrung als auch die Präsentation für unterschiedliche Zielgruppen. Peter Hruschka und Gernot Starke haben mit arc42 eine frei verfügbare, betont praxistaugliche Strukturvorlage zur Beschreibung von Softwarearchitektur entwickelt und eine erste Fassung bereits 2005 frei zur Verfügung gestellt [5, 6]. Meiner Erfahrung nach ist das Template in der Praxis mittlerweile weit verbreitet und erfreut sich einer hohen Akzeptanz. Bei arc42 handelt es sich sowohl um einen Ar- codekicker.de Die deutschsprachige Q&A-Plattform für Software-Entwickler codekicker.de Antworten für Entwickler

5 Kleines Einmaleins der Architekturdokumentation chitekturprozess als auch um eine Vorlage zur Architekturdokumentation. Motivation für die Entwicklung von arc42 war die aus Sicht der Autoren mangelnde Praxistauglichkeit und Schwergewichtigkeit der verfügbaren Lösungen. arc42 sollte helfen, dass nicht jedes Projekt bei null starten muss oder bei null Architekturdokumentation bleibt, weil der Aufwand etablierter Ansätze angeblich so hoch ist. Somit trifft arc42 die Intention dieses Artikels, gleichzeitig befolgen wir ein weiteres Mal Regel 4: Verwende eine Standardstrukturierung. Abbildung 5 zeigt die Gliederungsstruktur von arc42. Die Reihenfolge der insgesamt zwölf Kapitel lässt sich aus der Entwurfsmethodik heraus erklären. Der erste Teil der Inhalte (in der Abbildung markiert mit einem Dreieck) adressiert den Problemraum, also die Aufgabenstellung. Der zweite große Teil des Templates (markiert mit einem Pfeil) beschreibt die Lösung. Hierunter fallen Architekturentscheidungen, die Zerlegung des Systems in Teile (Bausteine) sowie das Zusammenspiel und Verhalten dieser Teile zur Laufzeit. Auch technische und übergreifende Konzepte finden hier ihren Platz. Die Abschnitte 5 bis 7 werden meist durch Abbildungen unterstützt. Sie fallen in den Bereich der Sichten, Thema in der nächsten Folge dieser Serie. Es folgen zwei Kapitel, die sich der Bewertung der Lösung zuordnen lassen (Stern). Qualitätsszenarien konkretisieren Qualitätsziele; sie erlauben es, die Lösung gegen die Aufgabe zu halten, dabei fallen als Ergebnis gegebenenfalls neue Risiken ab. Den Abschluss bildet ein Glossar, das Begriffe von der fachlichen Problemstellung bis zur technischen Umsetzung aufnehmen kann. Die Intention von arc42 wird oft missverstanden. Das zeigt sich in Aussagen wie Bei arc42 muss man dieses Word-Template ausfüllen. Die Urheber verstehen arc42 aber nicht nur als Vorlage, sondern vorrangig als Struktur zur Verwaltung, in der jedes Arbeitsergebnis, das im Rahmen des Architekturprozesses entsteht, seinen Platz findet. Hier fällt der meist im Englischen belassene Begriff Repository; dieser hat mit Fundgrube und Verwahrungsort recht aussagekräftige deutsche Entsprechungen. Aus dem Repository lassen sich dann zielgruppengerecht verschiedene Dokumente ableiten. Diese können als Inhaltsstruktur die Elemente des arc42-templates in der entsprechenden Reihenfolge [Abb. 5] Struktur von arc42. haben und in Umfang, Schwerpunkten und Detaillierung je nach Adressat variieren. Beispiele wären ein Architekturüberblick mit bis zu 30 Seiten oder auch ein Foliensatz zur Unterstützung eines Architekturüberblicks in Vortragsform. Wie flexibel und mit wie viel Aufwand Sie solche Dokumente aus Ihrem Repository ableiten können, hängt stark von der Wahl der Werkzeuge und Notationen ab. Ein einzelnes Word-Dokument mit dreistelliger Seitenzahl macht Sie unbeweglich. arc42 ist ein gutes Beispiel für eine Gliederung, aber natürlich nicht alternativlos. Sollten Sie bereits eine eigene Strukturierung für Ihre Architekturdokumentation einsetzen, gleichen Sie doch einmal ab, worin die Unterschiede liegen. Verorten Sie wichtige Teile (Ziele, Kontext, Entscheidungen). Auch wenn Sie arc42 nicht verwenden, kann es ein guter Ideengeber sein. Fazit und Ausblick Softwarearchitektur beschäftigt sich mit grundlegenden, später schwer änderbaren Entscheidungen. Um diese nachvollziehbar festzuhalten, genügt es allerdings nicht, die Lösung selbst zu dokumentieren. Ebenso müssen die Zielsetzung und die Einflussfaktoren festgehalten werden, welche die Architektur formen. Beim Dokumentieren einer Architekturentscheidung ist der Lösungsweg mindestens so interessant wie die getroffene Entscheidung. 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. Um all die Zutaten für einen Architekturüberblick aufzubereiten, gilt es, sie geeignet anzuordnen. Eine schlanke Standardvorlage wie arc42 gibt Orientierung und Sicherheit und spart Ihnen viel Arbeit, sich eine eigene Gliederung auszudenken. In der zweiten Folge dieser Artikelserie lernen Sie Sichten als Hilfsmittel kennen, um die Strukturierung Ihres Systems zu visualisieren und die Bestandteile in Interaktion untereinander und im Einsatz zu zeigen. Die Zutaten fügen sich nahtlos in arc42 ein. Auch die Frage nach Notationen und Werkzeugen gehen wir an. Muss es immer UML sein? Oder steht alles im Wiki? Oder was gibt es dazwischen? [bl] [1] Paul Clements et al.: Documenting Software Architectures: Views and Beyond, 2. Auflage, Addison-Wesley 2010, ISBN [2] DokChess, Beispiel für Architekturentwurf und -dokumentation, [3] Datenstruktur Bitboard bei Wikipedia, [4] Stefan Zörner, Softwarearchitekturen dokumentieren und kommunizieren, Hanser 2012, ISBN [5] arc42, [6]