Dokumentation von Software-Architekturen … nicht nur für Weicheier! Dr. Andreas Hörmann, Anwendungsentwicklung/Architektur/SE | JBFOne 2008

Ziel dieses Vortrags Sie verstehen, weshalb die Dokumentation von Software-Architekturen wichtig ist Sie haben eine Vorstellung davon, was wesentliche Bestandteile einer guten Architektur- Dokumentation sind Sie kennen die entsprechende Umsetzung der FIDUCIA in Form von SWAD

Agenda Hintergründe und Motivation Hintergründe und Motivation Einführung in SWAD Die wichtigsten Sichten von SWAD Umsetzung mit Dokumentationsbausteinen

Einordnung in den Software-Entwicklungsprozess Technisch Fachlich Anforderungs-spezifikation Konstruktion Einführung Betrieb Entwurf Entwicklungsphasen Plattform Guidelines (Host, JBF etc.) agree Standard- (aSA) und Subsystemarchitektur Fachliche Zielarchitektur (fZA) Richtlinien

Einordnung in den Software-Entwicklungsprozess Pflichtenheft Fachliche Konzeption Technische Programm- dokumentation Abnahme- Betriebs- Ergebnistypen Fachkonzept Programmkommentierung (Javadoc etc.) Programmhandbuch Systemhandbuch Vorlagen Technisch Fachlich Anforderungs-spezifikation Konstruktion Einführung Betrieb Entwurf Entwicklungsphasen Plattform Guidelines (Host, JBF etc.) agree Standard- (aSA) und Subsystemarchitektur Fachliche Zielarchitektur (fZA) Richtlinien

Einordnung in den Software-Entwicklungsprozess Technisch Fachlich Anforderungs-spezifikation Konstruktion Einführung Betrieb Entwurf Entwicklungsphasen Plattform Guidelines (Host, JBF etc.) agree Standard- (aSA) und Subsystemarchitektur Fachliche Zielarchitektur (fZA) Richtlinien Technische Konzeption Programm- dokumentation Software-Architektur- Dokumentation (SWAD) Pflichtenheft Fachliche Konzeption Technische Programm- dokumentation Abnahme- Betriebs- Ergebnistypen Fachkonzept Programmkommentierung (Javadoc etc.) Programmhandbuch Systemhandbuch Vorlagen

These: Echte Entwickler brauchen keine Dokumentation … Separates the men from the boys!

These: Die Wahrheit steckt im Programmcode …

Antithese: Darum ist Architektur-Dokumentation wichtig! Primäres Mittel zur effektiven Kommunikation über IT-Systeme Quellcode ist keine Architekturdokumentation: Umfang, Abstraktion etc. Auch Richtlinien (fZA, aSA) enthalten Freiräume, Optionen und ... weiße Flecken Grundlage für verteilte Entwicklung (imove, Vergabe externer Gewerke etc.) Überblick und Einstieg in IT-Systeme Lebensdauer übersteigt signifikant Erstellungszeit „Brainware“ ist keine geeignete Dokumentations- und Kommunikationsplattform Basis für Analyse und Bewertung Validieren durch Ausformulieren: Erst denken, dann tippen! Grundlage für Code- und Architektur-Reviews Bewertung von Qualitätseigenschaften Auswirkungsanalyse (impact analysis) bei Änderungen und Erweiterungen

Warum ein neuer Ergebnistyp? Existierende potentielle Kandidaten sind in die Jahre gekommen: Systemhandbuch Programmhandbuch … geben (zu) viele, oft spezifische Kapitel vor, die häufig leer bleiben … vermischen Aspekte von Konzeption, Installation und Betrieb … sind einseitig auf eine Plattform (Host) ausgerichtet … passen nicht zum HORIZON-Paradigma: EAM, SOA, Komponenten

Eine Vorgabe aus dem Elfenbeinturm? Nein! Grundlage für SWAD sind Ideen bzw. Vorarbeiten der so genannten „arc42“ Gruppe um Peter Hruschka und Dr. Gernot Starke ... die Erfahrungen aus vielen Entwicklungsprojekten in unterschiedlichen Branchen berücksichtigen … zahlreiche Best Practices zu diesem Thema umsetzen … hervorragend dokumentiert sind: Buch „Effektive Software-Architekturen“ Portal „www.arc42.de“

Agenda Hintergründe und Motivation Einführung in SWAD Die wichtigsten Sichten von SWAD Umsetzung mit Dokumentationsbausteinen

Anforderungen an eine „gute“ Architektur-Dokumentation Lesbar und verständlich Kurze und prägnante Beschreibungen Einheitliche Begrifflichkeit und Darstellungsstrukturen Steigender Detaillierungsgrad, Leser kann „Zoomfaktor“ wählen Konsistenz zu fachlichem Design und implementiertem Code „Keep it small and simple (KISS)“ Prinzip Keine Redundanzen – Verweise statt „Copy & Paste“ Flexibilität durch angemessene Vorgaben: Fixe Grobstruktur plus variabler Inhalt Wenige, klar abgegrenzte Dokumentationsbausteine Neutralität hinsichtlich Zielplattformen und Technologien „Single Documentation“ Ansatz Eine Dokumentation von Entwurf bis Konstruktion, die sukzessive verfeinert wird Anfängliches DV-Konzept (Soll) wächst zur Architekturdokumentation (Ist) heran

Diese Antworten gibt SWAD So fügt sich ein System in Strukturen seiner Umgebung ein Kontextsicht Verteilungssicht So ist es als eine Menge von Implementierungseinheiten strukturiert Bausteinsicht Datensicht So verhalten sich diese Elemente zur Laufzeit Laufzeitsicht Darum wurde so (und nicht anders) entworfen Entwurfsentscheidungen Architekturaspekte Bedeutung von Namen Glossar

Abgrenzung zur fachlichen Konzeption Informationen zum Projekt Anwendungsfälle Einbettung in fachliche Zielarchitektur Fachlicher Entwurf • Kanalspezifische Interaktion • Fachliche Komponenten und Services • Geschäftsobjekte • … Testfälle und -strategien Nichtfunktionale Anforderungen • Antwortzeiten • Mengengerüste • IT-Sicherheit • … Fachliche Konzeption Kontextsicht • Fachlich: Verweis auf Fachkonzept • Logisch: Einbettung in Gesamtsystem • Physisch: Kommunikationsbeziehungen Bausteinsicht • Überblick über alle Software-Bausteine • Black-/White-Box-Sicht pro Baustein Laufzeitsicht • Zusammenspiel der Bausteine Verteilungssicht • Abbildung auf Infrastruktur Datensicht Entwurfsentscheidungen Architekturaspekte Technische Konzeption Fach- konzept SWAD Ziel: Redundanzfreie, vollständige und angemessene Dokumentation von der Fachlichkeit bis zur Implementierung

Sichten als grundlegende Dokumentationselemente Herausforderung: IT-Systeme sind hochkomplexe Gebilde mit vielen Aspekten Lösung: Reduktion durch Abstraktion Einnahme eines Standpunktes Entfernung davon unnötiger Eigenschaften Schaffung einer vereinfachten Sicht auf Konzepte Analogie: Gebäudearchitektur

Sichten als grundlegende Dokumentationselemente /2 Für SWAD sind Sichten Modelle eines IT-Systems, die … von der Realität abstrahieren jeweils nur Teile einer Architektur aufzeigen sich auf bestimmte Details oder Aspekte konzentrieren die Darstellungskomplexität reduzieren Keine Sicht kann alle Aspekte einer Architektur aufzeigen! Best Practices für die Beschreibung von Sichten Sichten bestehen aus Diagrammen UND Erläuterungen … werden bei Bedarf Top-Down verfeinert werden … haben in der Regel 7+/- 2 Elemente pro Diagramm

Beispiel einer Sicht mit Optimierungspotential

Beispiel einer Sicht mit Optimierungspotential Das fällt auf … (Zu) Viele Aspekte in einer Sicht (Zu) Viele Details in einer Darstellung (Zu) Viele Elemente in einem Diagramm So könnte eine Optimierung aussehen … Eigene Sichten für Topologie, Infrastruktur, Software und Verteilung Bei Bedarf hierarchische Verfeinerung

Agenda Hintergründe und Motivation Einführung in SWAD Die wichtigsten Sichten von SWAD Umsetzung mit Dokumentationsbausteinen

Diese Antworten gibt SWAD (Reloaded) So fügt sich ein System in Strukturen seiner Umgebung ein Kontextsicht Verteilungssicht So ist es als eine Menge von Implementierungseinheiten strukturiert Bausteinsicht Datensicht So verhalten sich diese Elemente zur Laufzeit Laufzeitsicht Darum wurde so (und nicht anders) entworfen Entwurfsentscheidungen Architekturaspekte Bedeutung von Namen Glossar Vogelperspektive & Nachbarsysteme Kontextsicht Statische Struktur: Bausteine & Beziehungen Bausteinsicht A B B1 B2 B3 Wie arbeiten Bausteine zusammen? Laufzeitsicht C In welcher Umgebung laufen Bausteine ab? Verteilungssicht JBF IMS ORA

Diese Antworten gibt SWAD (Reloaded) So fügt sich ein System in Strukturen seiner Umgebung ein Kontextsicht Verteilungssicht So ist es als eine Menge von Implementierungseinheiten strukturiert Bausteinsicht Datensicht So verhalten sich diese Elemente zur Laufzeit Laufzeitsicht Darum wurde so (und nicht anders) entworfen Entwurfsentscheidungen Architekturaspekte Bedeutung von Namen Glossar Vogelperspektive & Nachbarsysteme Kontextsicht Statische Struktur: Bausteine & Beziehungen Bausteinsicht A B B1 B2 B3 Wie arbeiten Bausteine zusammen? Laufzeitsicht C In welcher Umgebung laufen Bausteine ab? Verteilungssicht JBF IMS ORA Vogelperspektive & Nachbarsysteme Kontextsicht

Die Kontextsicht Stellt eine Vogelperspektive oder konzeptionelle Übersicht dar Zeigt das System als Black-Box sowie dessen Verbindungen und Schnittstellen zur Umwelt Ist eine Sicht von außen auf hoher Abstraktionsebene Gliedert sich in folgende Aspekte: Fachlicher Kontext = die wichtigsten Anwendungsfälle (Use-Cases), in der Regel als Referenz auf fachlichen Entwurf Logischer Kontext = Schnittstellen zur Außenwelt, zu Anwendern, Betreibern und Fremdsystemen, inklusive der über diese Schnittstellen transportierten Daten oder Ressourcen Physischer Kontext = Technische Systemumgebung, Prozessoren, Kommunikationskanäle und -beziehungen

Beispiel: Logischer Kontext von System A

Beispiel: Physischer Kontext von System A

Beispiel: Logischer Kontext von System B

Beispiel: Physischer Kontext von System B

Diese Antworten gibt SWAD (Reloaded) So fügt sich ein System in Strukturen seiner Umgebung ein Kontextsicht Verteilungssicht So ist es als eine Menge von Implementierungseinheiten strukturiert Bausteinsicht Datensicht So verhalten sich diese Elemente zur Laufzeit Laufzeitsicht Darum wurde so (und nicht anders) entworfen Entwurfsentscheidungen Architekturaspekte Bedeutung von Namen Glossar Vogelperspektive & Nachbarsysteme Kontextsicht Statische Struktur: Bausteine & Beziehungen Bausteinsicht A B B1 B2 B3 Wie arbeiten Bausteine zusammen? Laufzeitsicht A B C In welcher Umgebung laufen Bausteine ab? Verteilungssicht JBF IMS ORA

Die Bausteinsicht Beschreibt die Zerlegung des Systems in Implementierungs- und Architekturbausteine Nutzt bei Bedarf eine hierarchische Abfolge von Black-Box- und White-Box- Beschreibungen Zeigt primär die statische Struktur des Systems Beantwortet folgende Fragen: Wie wird das System in Komponenten, Pakete, Klassen oder Subsysteme aufgeteilt? Welche notwendigen Abhängigkeiten zwischen Bausteinen gibt es?

Hierarchische Verfeinerung der Bausteinsicht Black-Box Beschreibung = Baustein-Außensicht Zweck/Verantwortung Schnittstellen Ablageort/Quellcodeverwaltung … White-Box Beschreibung = Baustein-Innensicht Zeigt Aufbau mit lokalen Bausteinen 1-n Enthält dafür jeweils eine eigene Black-Box Beschreibung

Beispiel: Bausteinsicht von System C

Beispiel: Bausteinsicht von System C

Diese Antworten gibt SWAD (Reloaded) So fügt sich ein System in Strukturen seiner Umgebung ein Kontextsicht Verteilungssicht So ist es als eine Menge von Implementierungseinheiten strukturiert Bausteinsicht Datensicht So verhalten sich diese Elemente zur Laufzeit Laufzeitsicht Darum wurde so (und nicht anders) entworfen Entwurfsentscheidungen Architekturaspekte Bedeutung von Namen Glossar Vogelperspektive & Nachbarsysteme Kontextsicht Statische Struktur: Bausteine & Beziehungen Bausteinsicht A B B1 B2 B3 Wie arbeiten Bausteine zusammen? Laufzeitsicht A B C In welcher Umgebung laufen Bausteine ab? Verteilungssicht JBF IMS ORA

Die Laufzeitsicht Beschreibt, welche Bestandteile des Systems zur Laufzeit existieren und wie diese zusammenwirken Ergänzt die Bausteinsicht um die dynamische Struktur des Systems Elemente sind Instanzen von Implementierungsbausteinen sowie deren Informations- und Kontrollflüsse Dokumentiert primär spezielle Aspekte der Laufzeit: Wie arbeiten die Systemkomponenten zur Laufzeit zusammen? Wie werden die wichtigsten Anwendungsfälle (Use-Cases) durch die Architekturbausteine bearbeitet? Welche Instanzen von Architekturbausteinen gibt es zur Laufzeit und wie werden diese gestartet, überwacht und beendet? Wie arbeiten Systemkomponenten mit externen und vorhandenen Komponenten zusammen? Wie startet das System (etwa notwendige Startskripte, Abhängigkeiten von externen Subsystemen, Datenbanken, Kommunikationssystemen etc.)?

Beispiel: Laufzeitsicht von System C

Beispiel: Laufzeitsicht von System D

Diese Antworten gibt SWAD (Reloaded) So fügt sich ein System in Strukturen seiner Umgebung ein Kontextsicht Verteilungssicht So ist es als eine Menge von Implementierungseinheiten strukturiert Bausteinsicht Datensicht So verhalten sich diese Elemente zur Laufzeit Laufzeitsicht Darum wurde so (und nicht anders) entworfen Entwurfsentscheidungen Architekturaspekte Bedeutung von Namen Glossar Vogelperspektive & Nachbarsysteme Kontextsicht Statische Struktur: Bausteine & Beziehungen Bausteinsicht A B B1 B2 B3 Wie arbeiten Bausteine zusammen? Laufzeitsicht A B C In welcher Umgebung laufen Bausteine ab? Verteilungssicht JBF IMS ORA

Die Verteilungssicht Beschreibt die Abbildung der Implementierungsbausteine auf die zugrunde liegende Infrastruktur Ergänzt die Baustein- und Laufzeitsicht um die Deployment-Struktur des Systems Elemente dieser Sicht sind Hardware-Knoten, ihre Verbindungen untereinander sowie die dort installierten Laufzeitkomponenten Zeigt bei Bedarf auch Leistungsdaten und Parameter der beteiligten Elemente Speichergrößen Kapazitäten Mengengerüste

Beispiel: Verteilungssicht von System C

Agenda Hintergründe und Motivation Einführung in SWAD Die wichtigsten Sichten von SWAD Umsetzung mit Dokumentationsbausteinen

Umsetzung mit Dokumentationsbausteinen Hauptdokument „Software-Architektur-Dokumentation (SWAD)“ Ist auf jeden Fall zu erstellen Vorlage für Microsoft Word in DB „EW-Richtlinien“, Kapitel 4.1.3.1

Umsetzung mit Dokumentationsbausteinen /2 Optionale Ergänzung durch „Software-Baustein-Dokumentation (SWBD)“ Für Implementierungseinheiten mit umfangreicher Funktionalität und/oder Reuse Kann zusätzlich erstellt werden Vorlage für Microsoft Word in DB „EW-Richtlinien“, Kapitel 4.1.3.1

SWAD – The Big Picture Software- Dokumentation (SWAD) Baustein- (SWBD) White-Box-Beschreibung B1 B2 B3 Black-Box-Beschreibung Verteilungssicht JBF IMS ORA Kontextsicht Laufzeitsicht A C Bausteinsicht Entwurfs- entscheidungen Architektur- aspekte Einführung, Überblick Datensicht Software- Dokumentation (SWAD) Baustein- (SWBD) Fachkonzept Code

… nicht nur für Weicheier! Zusammenfassung … nicht nur für Weicheier! Architektur-Dokumentation ist primäres Mittel zur Kommunikation über IT-Systeme Gute Dokumentation ist redundanzfrei, strukturiert, vollständig und angemessen Sichten fokussieren auf wichtige Aspekte und reduzieren die Darstellungskomplexität Die Software-Architektur-Dokumentation „SWAD“ ist die Umsetzung dieser Prinzipien in der FIDUCIA

… nicht nur für Weicheier! Fragen? – Diskussion? … nicht nur für Weicheier! Dr. Andreas Hörmann Anwendungsentwicklung └ Architektur └ Software Engineering (SE) andreas.hoermann@fiducia.de +49 721 4004 2057

Ihr IT-Partner Danke!