Keilschrift reloaded: Softwarearchitekturen besser dokumentieren

Gernot Starke, Stefan Zörner

© Shutterstock/Peshkova

Stellen Sie sich vor, Sie sollen Interessierten die Architektur Ihrer Software erklären – und es gibt keinerlei Dokumentation. Oder es stehen größere Änderungen an einem Altsystem an – und Sie können nirgendwo erkennen, welche Risiken dabei drohen oder ob man das System doch besser neu entwickelt. Ach, in diesem Dilemma stecken Sie wirklich? Dann sind Sie hier richtig.

„Der Quelltext ist die Dokumentation“. So lautet oft die Antwort von Projektteams auf die Frage, ob und wenn ja wie sie ihre Softwarearchitektur festhalten. Wir finden aussagekräftigen Code mit treffenden Bezeichnern, angemessener Dokumentation der öffentlichen Schnittstellen mit javadoc etc. wirklich gut. Aber dort finden Sie leider nur einen Teil der Architektur wieder. Der Quelltext erzählt, um es mit Simon Brown zu sagen, nicht die ganze Geschichte.

API Confernce 2019
 Maik Schöneich

gRPC – Ein neuer heiliger Gral?

mit Maik Schöneich

Oliver Drotbohm

REST Beyond the Obvious – API Design for Ever Evolving Systems

mit Oliver Drotbohm (Pivotal Software, Inc.)

 

Software Architecture Summit 2019
Stephan Pirnbaum

Lasst uns einen Monolithen (z)erlegen

mit Stephan Pirnbaum (buschmais GbR)

Scott Davis

Making Your Mobile Web App Talk

mit Scott Davis (ThoughtWorks)

Die ganze Geschichte

Bei der Softwarearchitektur eines Systems handelt es sich um fundamentale Strukturen, Konzepte, Entscheidungen und Lösungsansätze, die wesentlich sind, damit Systeme ihren Anforderungen genügen. Manchmal entsteht eine Softwarearchitektur nebenher und implizit während der Entwicklung. Die Erfüllung der Anforderungen (insbesondere der Qualitätsanforderungen wie Sicherheit, Performance, Wartbarkeit oder Robustheit) bleibt dann aus unserer Sicht dem Zufall überlassen. Wer darauf nicht wetten mag, weil das Risiko des Scheiterns zu hoch wäre, steckt Aufwand in die Softwarearchitektur. Er trifft Entscheidungen explizit, entwirft Schnittstellen, Strukturen und querschnittliche Konzepte systematisch. Die Ergebnisse methodischer Architekturarbeit schlagen sich zwar auch im Quelltext nieder, doch nicht alles findet sich dort, mitunter ist es zumindest gut versteckt. Lassen Sie uns einige Informationen betrachten, die wir aus Quelltext nicht rekonstruieren können:

• Begründungen für Entscheidungen: Warum haben wir diese Schnittstellen so gestaltet, warum haben wir die Anforderungen mit drei statt vier Komponenten erfüllt, warum haben wir diese statt jener Open Source Library eingesetzt?
• Verworfene Alternativen: Wir haben zuerst die naheliegende Lösung mit Framework X versucht, sind aber an Performance, Stabilität oder sonstigen Problemen gescheitert. Nun verwenden wir Y. Aber unsere gescheiterten Experimente stehen ja nicht mehr im Quellcode.
• Kriterien: Nach welchen Kriterien haben wir Entscheidungen oder Konzepte entworfen?

Darüber hinaus gibt es noch Architekturansätze, die sich zwar im Quelltext niederschlagen, aber schwer zu durchschauen sind:

• Übergreifende Ideen und Konzepte: Gleiche Probleme werden immer wieder gleich gelöst (konzeptionelle Integrität) – dieser Umstand ist aber im Quelltext kaum nachzuvollziehen und geht daher mit der Zeit leicht verloren.
• Strukturierung und (Kern-)Abstraktionen: Gerade bei einer großen Codebasis ist der Einstieg ohne „Landkarte“ schwer – auch wenn sich vieles mit Tools zur statischen Analyse ermitteln lässt, welchem neuen Entwickler wollen Sie das ernsthaft zumuten?

Eventtipp

foundation-level-logoadvanced-level-logo

Die Software Architecture Camps der Entwickler Akademie bieten iSAQB-zertifizierte Softwarearchitektur-Trainings – unter anderem mit Dr. Gernot Starke und Stefan Zörner. Alle Details auf www.software-architecture-camp.de.

Vogelperspektive gibt Überblick

Wir, die Autoren, mögen darüber hinaus Übersicht, etwa in Form einer Vogelperspektive auf das System. Die zeigt uns externe Schnittstellen, Nachbarsysteme und Typen von Benutzern – auf einer sehr hohen Abstraktionsebene. Meist nennen wir dies die Kontextabgrenzung (oder Kontextsicht). Quelltext ist für diesen Top-Level-Überblick ein schlechtes Medium, weil wir darin fast nie alle Außenschnittstellen auf einen Blick erfassen können. Im Beispiel von Abbildung 1 finden Sie die Vogelperspektive auf ein kleines Open-Source-Projekt [2]. Auf einen Blick erkennen Sie darin, dass es zwei unterschiedliche Benutzergruppen gibt (den „user“ sowie das Build-System), und drei externe Schnittstellen.

Abb. 1: Vogelperspektive

Abb. 1: Vogelperspektive

Ein wichtiger Grund für die explizite Kontextabgrenzung liegt im inhärenten Risiko beim Zusammenwirken mit externen Systemen begründet: An Außenschnittstellen gibt es oft mehr technische oder organisatorische Reibungspunkte oder Probleme als im Inneren unserer Systeme. Diese Probleme können wir mithilfe der Kontextabgrenzung recht gut „verorten“. Als Dokumentationsmittel ist die Kontextabgrenzung ein exzellentes Hilfsmittel, um das System kennenzulernen – ein Erstkontakt. Bevor ein Neuling in die Details einsteigt, versteht er am besten zunächst, mit wem das System interagiert und warum. Wir möchten neben der Außensicht aber natürlich auch das Innenleben unseres Systems verstehen und zeigen – daher geht’s als Nächstes ans Eingemachte.

Codestruktur in Groß und Klein

Ein wichtiges Ziel ist für uns die explizite Kenntnis der Codestruktur im Großen: Wir möchten wissen (und gerne auch dokumentieren), aus welchen strukturellen Einheiten (Komponenten, Modulen, Subsystemen o. Ä.) unser System aufgebaut ist. Die Betonung liegt auf „ist“: Die Wahrheit im Code zählt, nicht ein wunschtraumhaftes Lügengebilde. Haben Sie komplexe, eng gekoppelte Subsysteme? Dann zeigen Sie das ruhig – mit dieser Erkenntnis können wir besser leben als mit Vortäuschung falscher Tatsachen. Illustrieren können wir Codestrukturen mit fast beliebigen grafischen Mitteln – die architecture sketches von Simon Brown, pragmatische UML-Notation oder auch Freihandkästchen können je nach Einsatzgebiet helfen. Wir mögen einfache und im Team akzeptierte Mittel – sprechen Sie die Notation dieser „Bausteinsicht“ daher am besten mit dem Entwicklungsteam ab.

Abb. 2: Bausteinsicht

Abb. 2: Bausteinsicht

Abbildung 2 zeigt zur Illustration eine grobe Bausteinsicht des Html Sanity Check, dessen Kontextabgrenzung Sie bereits aus Abbildung 1 kennen. Wir zoomen hier in das System hinein und zeigen die grobe funktionale Struktur. Die Elemente sind typischerweise größer als Java-Klassen, oftmals auch größer als ein einzelnes Package. Auf dieser Ebene werden logische Bestandteile gezeigt, die Sie in weiteren Ebenen schrittweise verfeinern. Zu einem bestimmten Moment ist ein Kasten dann tatsächlich eine Klasse. Es ist in der Praxis aber selten sinnvoll, Diagramme anzufertigen, die das gleiche Abstraktionsniveau haben wie der Quelltext – der Aufwand, Dokumentation und Quelltext synchron zu halten, wäre zu hoch. Das schrittweise Verfeinern in der Bausteinsicht brechen Sie daher vorher ab. Ein Leser, der es genauer wissen will, schaut dann tatsächlich in den Quelltext. Um ihm diesen Schritt nahtlos zu ermöglichen, wählen Sie Bezeichnungen und Namen in Diagrammen/Dokumentation und Quelltext konsistent. Auch Verweise aus der Dokumentation in die betreffenden Stellen der Versionsverwaltung und/oder die aus dem Quelltext generierte Dokumentation sind probate Mittel.

Übergreifende Konzepte

Die Zerlegung des Systems in Teile, die Sie mit der Bausteinsicht schrittweise verfeinert visualisieren, öffnet einem Interessierten einen Einstieg in den Quelltext. Darüber hinaus halten Sie übergreifende Aspekte fest, zum Beispiel:

• Wie realisieren wir das UI?
• Wie überprüfen wir Berechtigungen?
• Wie speichern wir Daten?

Auch wenn der Quelltext hierzu natürlich die Implementierungen und mithin Beispiele zum Abgucken birgt, sind die Lösungsansätze für einen neuen Entwickler nur mühsam im Quelltext allein zu finden. Wenn Ihnen wichtig ist, dass diese Themen weiterhin einheitlich umgesetzt werden, sollten Sie die Ideen dazu geeignet kommunizieren. Ein erprobtes Mittel hierzu sind zielgruppengerechte Konzepte (UI-Konzepte, Securitykonzept, Persistenzkonzept etc.), oftmals mit Schritt-für-Schritt-Anleitungen (Tutorials). Das Herauslösen dieser Aspekte aus der Bausteinsicht hat auch den Charme, dass sich die Konzepte projektübergreifend weiterverwenden lassen, wenn es von den Anforderungen her passt.

Entscheidungen treffen und festhalten

Ein wichtiges Ziel von Architekturdokumentation ist die Nachvollziehbarkeit der Lösung. Für Ihre wichtigsten Entscheidungen hat sich das Festhalten des Weges dahin in strukturierter Form bewährt. Abbildung 3 zeigt hierzu einen Vorschlag, angelehnt an unserem Buch. Die Hauptäste geben dabei die Schritte im Entscheidungsprozess und zugleich die Unterkapitel in einer Dokumentation vor.

Abb. 3: Mindmap für eine Architekturentscheidung

Abb. 3: Mindmap für eine Architekturentscheidung

Das Praktische: Sie können die Struktur sowohl zum Treffen als auch zum Festhalten der Entscheidung verwenden – Entwurf und Dokumentation der Lösung erfolgen parallel. Das wirkt auch der in der Praxis leider verbreiteten Unart entgegen, erst am Ende zu dokumentieren, und es dann doch hinten herunterfallen zu lassen. Die Struktur in Abbildung 3 führt Sie (und später Ihre Leser) durch den Entscheidungsprozess, und nimmt insbesondere auch Dinge auf, die Sie im Nachhinein aus Quelltext oder Gedächtnis nur schwer (oder gar nicht) rekonstruieren können. Hierzu zählen die Problemstellung, betrachtete Alternativen und Bewertungskriterien. Dass beispielsweise ein bestimmtes Framework in der Lösung verwendet wird, sehen Sie der Lösung an. Ob dieses aber vorgegeben war oder Sie und Ihr Team sich bewusst entschieden haben, und vor allem warum, das macht genau eine nachvollziehbare Softwarearchitektur aus. Und den Unterschied zu „historisch gewachsen“. Die in Abbildung 3 vorgeschlagene Struktur kommt in Ihrer Dokumentation nur bei wichtigen Entscheidungen zum Einsatz. Also bei solchen Fragestellungen, die maßgeblichen Einfluss auf Ihre Architekturziele haben, oder deren Entscheidung eine weitreichende Wirkung entfaltet und/oder schwer änderbar ist. Einige moderne Definitionen setzen Softwarearchitektur mit diesen fundamentalen Entscheidungen gleich und unterstreichen die Wichtigkeit dieses Dokumentationsmittels.

Wo sammeln? – Übersicht gefragt

Sie haben nun einige bewährte Hilfsmittel zum Festhalten von Softwarearchitektur gesehen. Am einfachsten gelingt übersichtliche Dokumentation unserer Ansicht nach mithilfe fester Strukturen für die jeweiligen Ergebnisse oder Artefakte. Templates können hier helfen – wobei Ihnen völlig frei steht, welches Sie verwenden möchten. Wir mögen das (frei verfügbare) Architekturtemplate arc42 ( Übersicht siehe Abbildung 4). arc42 stellt eine pragmatische Struktur bereit, mit der Sie alle relevanten Informationen über die Architektur Ihrer Systeme einfach und sparsam aufheben und ordnen können. Die Inhalte zerfallen dabei grob in architekturrelevante Anforderungen, lösungsbezogene Inhalte und Bewertungsaspekte. Im Zusammenspiel ermöglicht eine Architekturbeschreibung nach arc42, den Lösungsentwurf nachvollziehbar festzuhalten. Die in diesem Artikel gezeigten Werkzeuge finden in der Gliederung in den Abschnitten 3 (Kontextabgrenzung), 5 (Bausteinsicht), 8 (Konzepte) und 9 (Entscheidung) ihren Platz.

Abb. 4: Gliederung nach arc42

Abb. 4: Gliederung nach arc42

arc42 ist insbesondere im deutschsprachigen Raum sehr verbreitet, aber nicht alternativlos, zeigt einen Vergleich zwischen der arc42-Gliederung und dem „Software-Guidebook“-Ansatz von Simon Brown. Die Gemeinsamkeiten sind groß. Projekte in einem regulierten Umfeld setzen oftmals auf vorgegebene Vorlagen aus Standards und Vorgehensmodellen. Projekte ohne solche Fesseln tun unserer Erfahrung nach gut daran, sich an pragmatischen Vorlagen zu orientieren, anstatt das Rad jedes Mal neu zu erfinden – oder gar zu laufen.

Die Werkzeugfrage

Die Gretchenfrage der Architekturdokumentation ist: „Wie halten wir es mit den Tools?“ Tatsächlich sind eine ganze Reihe von Aufgaben im Team zu bewältigen, bei denen Werkzeuge unterstützen können. Das beginnt mit dem Erstellen und Aktualisieren der Inhalte – in der Regel gemeinsam im Team. Weiterhin müssen Sie die Inhalte verwalten und ggf. mehrere Versionen pflegen. Und schließlich – Dokumentation ist kein Selbstzweck – wollen Sie die Inhalte im Team und an Dritte kommunizieren. Auch bei dieser Aufgabe können Tools unterstützen. Gerade bei Entwicklern ist der Einsatz eines Wikis in diesem Zusammenhang sehr beliebt. Die Stärken liegen u. a. im gemeinsamen Arbeiten und in der leichten Kommunikation der Inhalte an alle Beteiligten – Zugang zum Wiki vorausgesetzt. Wikis unterscheiden sich in ihrem Leistungsumfang erheblich. So gesehen lassen sich Vor- und Nachteile nicht leicht pauschalisieren. Zu den typischen Herausforderungen zählen das Liefern von etwas Druckfähigem (z. B. PDF) und Versionen über Seitengrenzen hinweg. Auch der Umfang mit Diagrammen ist immer wieder ein Diskussionspunkt und führt in der Regel zu Werkzeugketten (z. B. Wiki + UML-Tool).
In letzter Zeit erfreuen sich textbasierte Formate wie asciidoc oder Markdown großer Beliebtheit, da sie sich gut mit der ohnehin für den Quelltext vorhandenen Versionsverwaltung kombinieren und in den Build-Prozess integrieren lassen.

Der Einsatz von arc42 oder anderen Gliederungsvorschlägen ist übrigens nahezu unabhängig von der eingesetzten Werkzeugkette. Die Bandbreite der Möglichkeiten reicht von einem Word-Template über strukturierte Wikis bis hin zu strukturierten UML-Modellen. Auf GitHub finden Sie eine asciidoc-Fassung von arc42 – damit können Sie sehr codenah an der Dokumentation arbeiten und diese auch gleich in Ihren Build-Prozess integrieren. Bei der Auswahl der Werkzeuge für Ihr eigenes Projekt oder Unternehmen lassen Sie sich von den Anforderungen, Zielen und Zielgruppen leiten. Es gibt keine Patentlösung, die wir ohne jede Einschränkung jedem empfehlen können.

Wann ist Dokumentation gut genug?

Offen bleibt jetzt noch die Frage, ob oder wann Ihre Dokumentation denn gut genug für die beteiligten Personen ist? Dabei können Ihnen Ihre Stakeholder, d. h. die am Projekt oder System beteiligten Menschen, am besten Auskunft geben. Wir finden es bezüglich der Dokumentation hilfreich, vorab (ja, a-priori!) die Bedürfnisse und Erwartungen der Stakeholder zu erfragen. Dadurch können Sie Menge, Tiefgang, Abstraktionsgrad und auch Form Ihrer Dokumentation sehr genau auf die wirklichen Bedürfnisse abstimmen – und unserer Erfahrung nach gleichzeitig noch eine Menge Arbeit sparen: Vorher fragen stellt nämlich sicher, dass Sie niemals zu viel dokumentieren werden.

Weitere Antworten auf die Frage „Ist die Dokumentation gut genug?“ beziehen sich dann auf interne Konsistenz, auf Aktualität und Korrektheit, auf Konsistenz gegenüber dem Quellcode und auf Wartbarkeit – aber diese Details würden den Rahmen dieses Artikels sprengen.

Fazit, oder: Wie lernen Sie besser dokumentieren?

Kommen wir nochmals auf die Situation zurück, die am Anfang dieses Artikels geschildert wurde: Sie möchten Interessenten die Architektur Ihres Systems erklären. Wir haben Ihnen einige sehr pragmatische und einfache Mittel vorgestellt, mit deren Hilfe Sie hervorragend Architekturen erklären können. Sie haben eine breite Auswahl möglicher Werkzeuge gesehen – sodass Sie sich kaum noch herausreden können … Schmerzfreie, sparsame und effektive Dokumentation ist möglich. Nebenbei erwähnt: Die hier angesprochenen Ansätze können Sie auch im Advanced-Level-Modul des iSAQB e.V. zum Thema Architekturdokumentation vertiefen – und dieses Wissen dann unabhängig von Domäne, Branche oder Technologie zukünftig auf Ihre Systeme anwenden. Wir wünschen Ihnen viel Spaß – und Ihren zukünftigen Lesern ein gutes Verständnis.

Aufmacherbild: businessman presses skyscraper, high resolution von Shutterstock / Urheberrecht: Peshkova

Geschrieben von
Gernot Starke
Gernot Starke
    Informatikstudium an der RWTH Aachen, Dissertation über Software-Engineering an der J. Kepler Universität Linz. Langjährige Tätigkeit bei mehreren Software- und Beratungsunternehmen als Softwareentwickler, -architekt und technischer Projektleiter. 1996 Mitgründer und technischer Direktor des „Object Reality Center“, einer Kooperation mit Sun Microsystems. Dort Entwickler und technischer Leiter des ersten offizielle Java-Projekts von Sun in Deutschland. Seit 2011 Fellow der innoQ GmbH.  
Stefan Zörner
Stefan Zörner
Von der Bayer AG über IBM und oose zu embarc. Stefan Zörner blickt auf zwanzig Jahre IT-Erfahrung zurück und stets gespannt nach vorn. Er unterstützt in Architektur- und Umsetzungsfragen mit dem Ziel, gute Architekturansätze wirksam in der Implementierung zu verankern. Sein Wissen und seine Erfahrung teilt er regelmäßig in Vorträgen, Artikeln und Workshops. Stefan ist aktives Board-Mitglied im iSAQB und Autor des Buchs „Softwarearchitekturen dokumentieren und kommunizieren“ (Hanser-Verlag, 2. Auflage 2015). Twitter: @StefanZoerner
Kommentare

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
4000
  Subscribe  
Benachrichtige mich zu: