Jon Kowal Christian Sander Folie 1
Aufbau des Vortrags Einleitung Konzepte Dokumentation von Schnittstellen Dokumentation von Verhalten Auswahl von Views Zusammenstellen eines Documentation Package Folie 2
Einleitung Folie 3
Einleitung These pictures are meant to entertain you. There is no significant meaning to the arrows between the boxes A speaker at a recent software architecture conference, coming to a complex but ultimately inadequate boxes-and-lineseverywhere viewgraph of her system's architecture and deciding that trying to explain it in front of a crowd would not be a good idea. Folie 4
Einleitung Zum Vorgang des Dokumentierens Impliziert die Erzeugung eines Dokuments Konkrete Aufgabe Lässt sich an Artefakten festmachen Zerlegung in offene und erledigte Teile Erfassung im Projektmanagement möglich Folie 5
Einleitung Aspekte von SWA-Dokumentation Muss mehreren Ansprüchen genügen: Bildungsaspekt: Als Einführung in das System Kommunikationsaspekt: Soll als Basis für Kommunikation zwischen Stakeholdern dienen Stakeholder := Jeder, der ein Interesse an der SWA hat Folie 6
Einleitung Übersicht: Stakeholder Architekt & Anforderungsdesigner Manager (aus Kundensicht) Qualitätssicherung SWA-Doku Programmierer Wartung Tester Folie 7
Einleitung Wiederholung: Viewtypes Module Structures Component-Connector-Structure Element als Module betrachten Elemente und ihre Relationen zueinander Allocation Structure Beziehungen von Elementen zur äußeren Umgebung SWA-Doku soll relevante Views und zusätzliche Informationen enthalten Folie 8
Einleitung Sieben Regeln für eine gute Dokumentation (1-4) 1. Doku aus der Sicht des Lesers schreiben Insiderjargon vermeiden 2. Unnötige Wiederholungen vermeiden 3. Mehrdeutigkeiten vermeiden Notationen erläutern 4.Standardisierte Organisationsschemata verwenden Gutes Referenzieren ermöglichen Folie 9
Einleitung Sieben Regeln für eine gute Dokumentation (5-7) 5.Entscheidungswege aufzeichnen Alternativen und Argumente festhalten 6.Doku aktuell halten aber nicht zu aktuell Enwicklungsplan sollte Phasen für Aktualisierung enthalten 7.Reviews für Doku durchführen Erfüllt die Doku beim Zielpublikum ihren Zweck? Folie 10
Konzepte Folie 11
Einleitung >> Konzepte Chunking information View Packets Ein View kann tausende Elemente enthalten Zerlegung in chunks (= view packet) View Packet ist das kleinste zusammenhängende Bündel an Dokumentation Folie 12
Einleitung >> Konzepte View Packets: Typen (1) Same-View View Packets View Packets stehen in Geschwister - oder Kind -Relation Geschwister: dokumentieren unterschiedliche Teile des Systems (ergänzen sich) Kind: dokumentieren denselben Teil eines Systems nur unterschiedlich detailliert Relationen der View Packets als Baum darstellbar Folie 13
Einleitung >> Konzepte View Packets: Typen (2) View Packets from different Views: Fälle 1) Beschreibung verschiedener Bereiche des Systems mit unterschiedlichen Styles 2) Ein Element des eines Styles wird durch Elemente eines anderen Styles beschrieben 3) keine klare Abgrenzung der Styles; Vermischung zur Beschreibung eines Systems Folie 14
Einleitung >> Konzepte View Packets from different Views: Beispiele Folie 15
Einleitung >> Konzepte View Packets: Refinement Refinement Decomposition refinement Verfeinerung, die die Beschreibung des parent erweitert Interne Struktur eines Elements wird rekursiv verfeinert Implementation refinement Elemente und Relationen werden durch implementationsspezifischere Elemente und Relationen ersetzt Folie 16
Einleitung >> Konzepte View Packets: Descriptive Completeness (1) Descriptive Completeness View Packets, die alle Elemente und Relationen zueinander enthalten Vorteil: Überprüfung auf Konsistenz leichter Alternative: Noncompleteness Nicht vorhandene Elemente und Relationen können in Refinements auftauchen Vorteil: Intuitiverer Ansatz um Modelle zu formulieren Folie 17
Einleitung >> Konzepte View Packets: Descriptive Completeness (2) Beispiel Wie sieht die Relation zwischen A und C aus? Existiert überhaupt eine? Folie 18
Einleitung >> Konzepte Kontextdiagramme (1) Definition Motivation Enthält ein System (oder ein Teil davon) sowie die externen Akteure, die mit ihm interagieren Dient der Orientierung des Lesers Top-Level Kontextdiagramm (TLCD) Oberste Ebene; Zeigt das gesamte System Folie 19
Einleitung >> Konzepte Kontextdiagramme (2) Hinweis Für jedes View Packet sollte ein Kontextdiagramm existieren Beispiel Folie 20
Einleitung >> Konzepte Combined View (1) Definition Ein View der Elemente oder Relationen enthält, die aus zwei oder mehr Views stammen Motivation Soll starke Relation zwischen unterschiedlichen Views betonen Erleichtert die Einarbeitung in das System Weniger Wartung der Doku (Alle Views auf selbem Stand?) Folie 21
Einleitung >> Konzepte Combined View (2) Möglichkeiten 1) Mapping zwischen separaten Views Bei sehr großen Systemen unvermeidlich 2) Schaffung eines Overlay Zusammenlegen der Informationen aus mehreren Views zu einem neuen 3) Schaffung eines hybrid style Kombination mehrerer Styles zu einem neuen Style Folie 22
Einleitung >> Konzepte Combined Views: Beispiel Folie 23
Einleitung >> Konzepte Variabilität und Dynamik Hintergrund Variabilität Architektur-Entscheidungen, die noch nicht gefällt wurden, müssen trotzdem dokumentiert werden Bezieht sich auf Entscheidungen, die vom Entwicklungsteam vor der Systementwicklung getroffen werden Dynamik Bezieht sich auf Entscheidungen, die vom System während der Ausführung getroffen werden Folie 24
Einleitung >> Konzepte Variabilität und Dynamik: Beispiel Folie 25
Dokumentation von Software-Schnittstellen Folie 26
Einleitung >> Konzepte >> Doku von Schnittstellen Schnittstellen: Prinzipien Alle Elemente haben Schnittstellen Schnittstellen sind zweiwegig Anforderungen und Ergebnisse, die geliefert werden Elemente können mehrere Schnittstellen besitzen Ein Element kann durch ein und dieselbe Schnittstelle mit mehr als einem actor interagieren Es bietet sich an Schnittstellen-Typen und -Instanzen zu verwenden Folie 27
Einleitung >> Konzepte >> Doku von Schnittstellen Schnittstellenspezifikation Definition All das, was der Software-Architekt über die Interaktionsmöglichkeiten eines Elements bekannt gibt Richtlinien Der Fokus sollte auf der Interaktion mit der Umwelt liegen (nur sichtbare Effekte) Nur so viel wie wirklich nötig ist dokumentieren So präzise wie möglich fassen (möglichst keine Ermessensspielräume lassen) Redundanz vermeiden: nur eine Spezifikation und ggf. Referenzen verwenden Folie 28
Einleitung >> Konzepte >> Doku von Schnittstellen Organisationschema zur Schnittstellendoku Folie 29
Einleitung >> Konzepte >> Doku von Schnittstellen Exceptions und Error Handling Error Handlung: Möglichkeiten Rückgabe von Statusinformationen Wiederholen der Anfrage Fallback-Mechanismen Exceptions: Klassifikation Folie 30
Einleitung >> Konzepte >> Doku von Schnittstellen Notationen (1) Existenz einer Schnittstelle dokumentieren Informale Darstellung Schnittstelle sollte explizit ein Symbol erhalten, wenn ein Element mehrere Schnittstellen besitzt Folie 31
Einleitung >> Konzepte >> Doku von Schnittstellen Notationen (2) Syntaktische Informationen Mittels IDL (Interface Definition Language) Von der OMG (Object Management Group) definierte Sprache Erlaubt die Beschreibung von Datentypen, Operationen, Attributen und Exceptions Aber: keine Semantik (außer mögliche Kommentare) Semantische Information Informal Boolsche Algebra (Vor- und Nachbedingungen) Sequenzen Folie 32
Einleitung >> Konzepte >> Doku von Schnittstellen Beispiele: IDL // Beispiel Banksystem interface Account { readonly attribute string owner; readonly attribute float balance; void deposit (in float amount); void withdraw (in float amount); }; interface SavingsAccount: Account { float annual_interest(); } interface CheckingAccount: Account { readonly attribute float overdraft_limit; void order_new_checks(); } interface Bank { CheckingAccount open_checking(in float starting_balance); SavingsAccount open_savings(in string name, float starting_balance); } Folie 33
Einleitung >> Konzepte >> Doku von Schnittstellen Beispiele: SCR (Software Cost Reduction [U.S. Navy Project]) Auschnitt (Wirkung einer Schnittstelle Bsp.: Baum) +add_first++g_num+(p1) = 1+'+g_num+'(p1) +g_nth+(p1,1) = p2 For all i: integer such that (1<i and i<=1+'+g_num+'(p1)), +g_nth+(p1,i) = '+g_nth+'(p1,i-1) +g_num+(p1) > 1 ==> ( +g_next+(p2) = '+g_nth+'(p1,1) and +g_prev+('+g_nth+'(p1,1)) = p2 ) +g_parent+(p2) = p1 For all n:!<n>!, '+g_is_in_tree+'(p1,n) ==> ( +g_size+(n) = '+g_size+'(n) + +g_size+(p2) and For all k:!<n>!, +g_is_in_tree+'(k,p2) ==> +g_is_in_tree+(k,n) ) Folie 34
Dokumentation von Verhalten Folie 35
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Dokumentation von Verhalten Mehr semantische Information hinzufügen Zeitverhalten in Interaktion einbeziehen Reihenfolge von Interaktionen zwischen Elementen Gelegenheiten zu Konkurrenz Zeitabhängige Interaktionen (bestimmte Zeitpunkte, Perioden) Bsp. für Dokumentationsmöglichkeiten in UML Interaktionsdiagramme Zustandsdiagramme Folie 36
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Warum Verhalten dokumentieren? Systemanalyse Simulation des Systems Korrektheit und andere Qualitätsmerkmale prüfbar ABER: Simulation verlangt Kenntnis über das Verhalten Unterstützen der Entwicklung Weniger Rätselraten Beispiel Gateway: Strukturdiagramme zeigen nur, dass Nachrichten ein und ausgehen, aber nicht dass z.b. mehrere eingehende Nachrichten zu einer ausgehenden verschmelzen können. Folie 37
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Was muss vom Verhalten dokumentiert werden? Minimum Aktionsauslöser (Stimulation of actions) zwischen Elementen Informationsflüsse zwischen Elementen Zeitliche Vorbedingungen oder Reihenfolgen, falls Korrektheit des Programms davon abhängt. Allgemein Jedes zusätzliche Detail über Beschränkungen der Interaktion zwischen Elementen verbessert mögliche Verhaltensanalyse und somit (hoffentlich) Qualität der Implementation. Folie 38
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Was muss vom Verhalten dokumentiert werden? Kommunikationstypen Synchron Daten Aufruf Beides Asynchron Datenbank Prozeduraufruf ohne Parameter Interrupt, Ereignis ohne Parameter Prozeduraufruf mit Parameter Message, Ereignis mit Parameter Beschränkung der Reihenfolge Reihenfolge von Aufrufen Einander bedingende Ereignisse Ausgabe von Zwischenergebnissen möglich? Verwertung von Parameterteilen möglich? Zeitgesteuerte Stimulation Folie 39
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Zwei Dokumentationskategorien traces Beschreiben (Verfolgen) von Szenarien nur bestimmte Zustände betrachten unvollständig in Hinblick auf Gesamtsystem static models vollständiges, statisches Modell meist zustandsbasiert alle Pfade des Systems können verfolgt werden Folie 40
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Zwei Dokumentationskategorien Vorteil traces Betrachtet nur die Ressourcen, die für ein bestimmtes Szenario bedeutsam sind Nachteil traces Ein trace kann nur einen Bruchteil des Verhaltens eines bestimmten Elements zeigen Vorteil static models Betrachtet meist alle mit den Schnittstellen eines Elements verbundenen Ressourcen Nachteil static models Um systemweites Verhalten zu betrachten, muss man auf verschiedene statische Modelle zugreifen. Folie 41
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Notationsmöglichkeiten für traces Use Cases Interaktionen zw. Elementen und Aktoren der Umwelt Notation meist textuell Use Case Maps Stellt Pfade zwischen Use Cases dar. (grafisch) Sequenzdiagramme Kollaborationdiagramme Message Sequenz Charts Folie 42
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Use Case Map: Beispiel Folie 43
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten Notationsmöglichkeiten für static models State charts (Zustandsgraphen) State based languages z.b. SDL, Z Folie 44
Auswahl von views Folie 45
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views Offene Fragen Was soll nun dokumentiert werden? Bis zu welchem Detail ist zu dokumentieren? Wieviele Views genügen? Wieviele sind zu viel? Wie vollständig muss das Ganze sein? Wichtig: Verständnis dafür, welche kurzfristigen Einsparungen welche langfristigen Kosten auf den Plan rufen. Folie 46
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views Offene Fragen Antwort auf Fragen, wenn bekannt ist Welche Leute stehen zur Verfügung / Skills? Budget? Schedule? Wer sind die wichtigen Stakeholder? Folie 47
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views Beispiele für wichtige Stakeholder: Projekt Manager Interessen Top level context Diagramm (module viewtype) Decomposition, uses und/oder layered view (module viewtype) Work assignment view (allocation viewtype) Deployment view (allocation viewtype) Folie 48
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views Beispiele für wichtige Stakeholder: Entwickler Interessen Globales Verständnis für das System Welches Element wurde ihm Zugewiesen? Kann vorhandener Code genutzt werden? Welcher? Qualitätsanforderungen und sonstige Einschränkungen Folie 49
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views Beispiele für weitere wichtige Stakeholder Tester und Integrierer Designer anderer Systeme Maintainers Kunden Endnutzer Analysten... Folie 50
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views View-Auswahl treffen Wie kann view-auswahl nun bestimmt werden? Auswahl der views hängt stark von Erwarteter Nutzung ab Es sollte zu jedem der 3 viewtypes (module, component & connector, allocation) mind. 1 view erstellt werden Für weitere views: Stakeholders fragen In Größeren Projekten sogar Workshop mit Stakeholders denkbar, um deren Bedürfnisse in Erfahrung zu bringen. Folie 51
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views View-Auswahl treffen Stakeholder / view Tabelle aufbauen, z.b. Folie 52
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views View-Auswahl treffen Schrittfolge zum Ziel Stakeholder/view Tabelle aufbauen (wie bereits beschrieben) Combine Views wenig verlangte views in der Tabelle erkennen. Gibt es äquivalente, kombinierte Ersatzviews? Andere Views betrachten, die gute Kandidaten für Vereinigung sind, z.b.: work assignment, implementation module decomposition view Priorisieren Minimum Viewset liegt vor, was zuerst tun? paralleles Arbeiten an Views möglich Folie 53
Zusammenstellen von Documenation Packages Folie 54
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Allgemeines Zwei Möglichkeiten 1 großes Dokument mehrere separate Dokumente wichtig für alle Dokumente Erstelldatum und Status Name der herausgebenden Organisation Change History Zusammenfassung wichtig im Package Glossary of Terms Folie 55
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Einen view dokumentieren Erinnern: view ist Sammlung von view-paketen Template for a view packet Primary Presentation of the View Packet Element catalog Context diagram Variability Guide Architecture Background Other Information Related view packets Folie 56
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Template für ein view packet Primary presentation zeigt Elemente und deren Zusammenhänge in diesem view Packet Beschreibt (im Vokabular des Views), welche Information man über das System mitteilen möchte Notation meist grafisch, aber auch textuell möglich Folie 57
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Template für ein view packet Elementkatalog Elemente und ihre Eigenschaften Beziehungen und ihre Eigenschaften Elementschnittstellen Elementverhalten Architecture Background Warum das Design genau so? Annahmen, Analysen, versteckte Logik,... Folie 58
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Documentation Beyond Views Es gibt noch mehr als nur views Verbindung zwischen Views muss geschaffen werden Der Leser soll an die Architektur herangeführt werden und schnell zu den für ihn relevanten Teilen finden 3 Hauptpunkte für documentation beyond views Wie ist die Dokumentation organisiert? Was stellt die Architektur dar? Warum ist die Architektur wie sie ist? Folie 59
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Wie ist die Dokumentation organisiert? Documentation Roadmap Beschreiben der Bestandteile des Documentation packages Zu jedem view liefert die Roadmap Name des view und style Beschreibung der view-elementtypen, Relationstypen, und Eigenschaftstypen Beschreibung wofür der view gedacht ist Beschreibung der verwendeten Sprachen, Techniken,... Beschreibung, wie Stakeholders auf das package zugreifen können View Template Folie 60
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages View Template: Beispiel Folie 61
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Was stellt die Architektur dar? Überblick über Gesamtsystem geben mapping zwischen views herstellen Verzeichnis Tabelle kann verwendet werden, um Elemente aus verschiedenen views aufeinander abzubilden Verzeichnis aller Elemente aus allen views erstellen, mit Zeiger auf die Definition Glossar + Akronyme Folie 62
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Warum ist die Architektur wie sie ist? Design constraints, rationale, background Dokumentieren, warum bestimmte Entscheidungen getroffen wurden Alternativen, die betrachtet wurden aufzeigen Begründen, warum Alternativen verworfen wurden Zeigen, warum die Entscheidungen so gut waren Folie 63
Einleitung >> Konzepte >> Doku von Schnittstellen >> Doku von Verhalten >> Auswahl von views >> Doc Packages Architektur Dokumentation validieren Reviews mögliche Fragen Ist die Dokumentation konsistent mit der Stakeholdercommunity, die sie benutzen wird? Ist die Dokumentation konsistent mit sich selbst? Widersprüche? Korrekte Abbildungen der views? Ist die Form der Dokumentation konsistent? Werden Abschnitte durch Templates oder andere Standards definiert? (Bsp. view template) Ist die Dokumentation konsistent mit der Architektur, die sie beschreiben soll? Folie 64
Dieser Vortrag basiert auf dem Buch: Documenting Software Architecture: views and beyond by: Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, Judith Stafford Folie 65