„View“-basierte Softwarearchitektur-Dokumentation

Eine Softwarearchitektur sinnvoll zu dokumentieren bedeutet, die relevanten Informationen des Systems so zu erfassen, dass diese jederzeit wieder abgerufen werden können. Was aber sind relevante Informationen, und wie halte ich sie so fest, dass Aufwand und Nutzen in sinnvollem Verhältnis stehen?

Anbieter zum Thema

Axivion GmbH

Parasoft® Deutschland GmbH

RTI Real-Time Innovations

visuellklar M. Künzi

Das Thema Softwarearchitektur-Dokumentation lässt sich anhand des sogenannten „Golden Circle“ (siehe Bild 1) in drei Schritten erklären. Am Anfang steht immer die Frage: „Warum“? Warum sollte man Architektur überhaupt dokumentieren. Danach folgt das „Wie“. Hier ist die View-basierte Dokumentation das Hauptthema. Abschließend folgt noch das „Was“: Was genau muss denn nun wirklich dokumentiert werden?

Warum ist die Dokumentation der Softwarearchitektur sinnvoll?

Software Architektur dokumentieren – warum? Was ist der Nutzen einer solchen Dokumentation? Es gibt aus meiner Sicht und Erfahrung die folgenden zwei Haupt Use-Cases, bei welchen eine Architektur Dokumentation ein essentielles Hilfsmittel ist (Bild 2):

Bildergalerie

Bildergalerie mit 8 Bildern

1. Analyse, Review oder Prüfung der Software z. B. für folgende Aufgaben:
a. Architektur-Review, bevor das System gebaut wird (Earliest Artefact to Analyse)
b. ATAM Analyse zur Sicherstellung der auferlegten Qualitätsanforderungen
c. Aufzeigen der Erfüllung von regulatorischen Auflagen (Medtech, Safety,..)
d. Impactanalyse einer Software-Änderung (zusätzliche oder geänderte Anforderungen). Wartung eines Softwaresystems.
e. …

2. Erklären, schulen des Aufbaus der Software z. B. für folgende Szenarien:
a. Erklären des geplanten Aufbaus des Systems innerhalb des Entwicklerteams. Sicherstellen, dass das Softwaresystem, so wie geplant, gebaut wird.
b. Einarbeitung neuer Projektmitarbeiter
c. Ableiten der Aufwände zur Entwicklung des Systems (Work Estimation).
d. Ableiten geeigneter Schnittstellen für die Abarbeitung (Work Assignment)
e. Aufzeigen der gemachten Design-Entscheidungen. Verhindern, dass die gleichen Fragestellungen später wieder aufgeworfen werden.
f. …

Es gibt also einen klaren Nutzen einer Architektur-Dokumentation. Zusammenfassend ist die Dokumentation einer Architektur ein wichtiges Kommunikationsvehikel im LifeCycle eines Softwaresystems.

Was aber ist mit dem Verhältnis Aufwand zum Nutzen? Wieviel Aufwand lohnt sich in eine Dokumentation zu investieren? Das ist eine sehr gute und berechtigte Frage. Obwohl man sich die oben aufgeführten Use Cases gut vorstellen kann, sind diese noch lange nicht für jedes System relevant. Es lohnt sich also in jedem Fall den konkreten Nutzen dem Aufwand gegenüberzustellen.

Das heißt, diese Formel anzuwenden:

A = ∑ Kosten für Erstellung SAD – ∑ Zusatzkosten für Use Cases ohne SAD

Wenn diese Formel einen negativen Wert ergibt, dann lohnt sich der Aufwand für die Erstellung einer Dokumentation. Allerdings muss man hier den gesamten LifeCycle eines Systems betrachten. Eine sinnvolle Architektur-Dokumentation wird im gesamten LifeCycle immer wieder gebraucht werden.

Insbesondere ist eine geeignete Softwarearchitektur-Dokumentation nach der Erstentwicklung sehr hilfreich. Und wenn man das Verhältnis zwischen Initialentwicklung und Wartungs- und Weiterentwicklungsaufwand eines typischen Softwaresystems betrachtet, dann umso mehr (Bild 3).

„Working Software over comprehensive documentation“. Dieser agile Grundsatz aus dem Manifest ist richtig und wichtig. Er sagt aber nicht aus, dass es keine Dokumentation geben soll. Die Meinung hier ist aber, dass es genau um die richtige Balance zwischen Aufwand und Nutzen geht.

Es heißt ja nicht, dass keine Dokumentation erstellt werden soll, sondern nur, dass die laufende Software über der Dokumentation stehen soll – oder eben auch, dass eine sinnvolle Dokumentation eine Basis für laufenden Software sein soll (Bild 4).

Wie sollte eine sinnvolle Dokumentation erstellt werden?

Für eine Softwarearchitektur-Dokumentation wie auch für andere Dokumentationen gibt es ein paar sinnvolle Grundsätze:

1. Schreibe für den Leser
2. Vermeide unnötige Wiederholungen
3. Vermeide Mehrdeutigkeiten und Unklarheiten
4. Verwende, wenn immer möglich eine Standard Struktur der Dokumentation
5. Dokumentiere auch Hintergründe und Begründungen
6. Stelle sicher, dass die Dokumentation aktuell ist – aber vermeide unnötige und häufige Aktualisierungen
7. Lass die Dokumentation überprüfen

Auf die Punkte 1, 3 und 4 wird nachfolgend genauer eingegangen:

Schreibe für den Leser
Das bedeutet auch, man sollte die Stakeholder seiner Dokumentation kennen, d. h. die Nutzer. Es lohnt sich also hier eine Stakeholder-Map zu machen und sich zu überlegen, welche Informationen jeder Stakeholder haben sollte.

Da verschiedene Stakeholder unterschiedliche Informationsbedürfnisse haben, macht es Sinn, verschiedene Sichten zu erstellen und dadurch eine umfassende Stakeholder-basierte Dokumentation zu erstellen. Das Beispiel in Bild 5 aus der Anatomie soll die Begriffe View (Ansicht), Stakeholder (Interessengruppe) und Concerns (Interessen) veranschaulichen.

Bild 6 und 7 zeigen einen Auszug aus einem konkreten Beispiel einer Architektur View.

Vermeide Mehrdeutigkeiten und Unklarheiten
Für eine gute Dokumentation ist Klarheit essentiell. Speziell für eine Softwarearchitektur-Dokumentation kann man viel Klarheit mit Bildern, d. h. Diagrammen erreichen. Allerdings ist hier Vorsicht geboten. Diagramme müssen klar verständlich sein. Hier helfen entweder Standarddiagramme wie UML zu verwenden – oder mit klaren Legenden die verwendeten Symbole und Diagrammelemente zu erläutern. Das folgende Beispiel eines Diagramms aus einer Architektur View zeigt, wie das aussehen könnte (Bild 8).

Verwende, wenn möglich, eine Standardstruktur der Dokumentation
Eine klare immer wieder verwendete Struktur einer Dokumentation hilft enorm. Die in Bild 9 gezeigten Strukturen für eine View sowie für eine komplette Softwarearchitektur-Dokumentation haben sich in der Praxis wiederholt bewährt

Bildergalerie

Bildergalerie mit 8 Bildern

Zu beachten ist hier, dass eine View nicht einfach ein Diagramm ist, sondern dass eine komplette View anhand obigem Template dokumentiert werden sollte.

Was genau sollte dokumentiert werden?

Klar, die „Software-Architektur“ soll dokumentiert werden. Aber was ist das genau? Dazu lohnt es sich, die Definitionen von Architektur anzuschauen. Insbesondere der Unterschied zwischen Design und Architektur. Das gibt nämlich neben den benötigten Informationen der Stakeholder eine gute Entscheidungshilfe, was dokumentiert werden soll und was nicht.

„The set of structures needed to reason about the system, which comprises software elements, relations among them, and properties of both. The definition emphasizes the plurality of structures present in every software system. These structures, carefully chosen and designed by the architect, are the key to achieving and reasoning about the system’s design goals. And those structures are the key to understanding the architecture.”

(Aus „Documenting Software Architectures” Views and Beyond (2nd Edition), Clements et al, Addison-Wesley, 2010)

„All architecture is design but not all design is architecture. Architecture represents the significant design decisions that shape a system, where significant is measured by cost of change.” (Grady Booch)

Genau diese Definitionen sind aus meiner Erfahrung zu Hilfe zu nehmen, um sicherzustellen, dass die notwendige (=essentielle) Dokumentation vorhanden ist, und aber, dass nicht alle Details dokumentiert werden. Zudem ist nach diesen Definitionen auch sichergestellt, dass diese Art der Dokumentation einen langen Bestand hat und nicht dauernd aktualisiert werden muss. Also genau das Ziel, was erreicht werden sollte.

Zusammenfassung

1. Aufwand und Nutzen einer Architektur-Dokumentation sollte in einem sinnvollen Verhältnis stehen.
2. Verwende Views, um eine Stakeholder-basierte Architektur zu erstellen.
3. Beachte, eine View ist nicht einfach ein Diagramm, sondern enthält genau die Information, welcher für die entsprechenden Stakeholder relevant sind.
4. Stelle sicher, dass die gesamte Dokumentation insbesondere Architekturdiagramme klar und unmissverständlich sind. Verwende eine Diagrammlegende, wenn nötig.
5. Dokumentiere die Architektur relevanten Teile und nicht Design- und Implementationsdetails.

Functional Safety Software Engineering: Problemfälle Prozess & Qualität

Ist Architektur-Entwicklung überhaupt noch zeitgemäß?

Literatur- und Quellenverzeichnis

• Documenting Software Architectures: Views and Beyond (2nd Edition) von Paul Clements, Felix Bachmann, Len Bass , David Garlan u.a.; Publisher: Addison-Wesley Professional; 2 edition (October 15, 2010)

• 4+1 architectural view model (Philipp Kruchten) https://en.wikipedia.org/wiki/4%2B1_architectural_view_model

• ISO/IEC 42010

(Dieser Beitrag wurde mit freundlicher Genehmigung des Autors dem Tagungsband Embedded Software Engineering Kongress 2018 entnommen.)

Der Autor

* Mit seiner eigenen Firma „visuellklar“ berät und unterstützt Matthias Künzi Firmen bei der Umsetzung komplexer Problemstellungen im Projekt- und Softwareumfeld. Dabei kommen vor allem visuelle und agile Methoden zum Einsatz.

(ID:45814688)