In zahlreichen Unternehmen gehört arc42 (siehe [arc42]) heute zu den etablierten Hilfsmitteln für die Entwicklung, Kommunikation und Dokumentation von Softwarearchitekturen. arc42 ist ein pragmatisches Template, gedacht für alle Beteiligten an Software- und Systementwicklung. Sie können arc42 komplett frei verwenden, da es unter einer liberalen Open-Source-Lizenz erstellt und publiziert wird. arc42 stammt aus der Praxis und basiert auf Erfahrungen internationaler Architekturprojekte und Rückmeldungen vieler Anwenderinnen und Anwender.
arc42 eignet sich für beliebige Technologien und Werkzeuge. Es passt großartig zu agilen und iterativen Entwicklungsvorgehen, aber auch andere Organisationsformen profitieren davon. Neben dem Template schlägt arc42 einige Kernaufgaben zur Entwicklung und Konstruktion effektiver Softwarearchitekturen vor, auf die ich in diesem Artikel allerdings nicht weiter eingehe.
arc42 stammt von Dr. Gernot Starke und Dr. Peter Hruschka: Wir beide haben 2002 angefangen, unsere Erfahrungen vieler Entwicklungs- und Architekturprojekte zusammenzutragen und eine flexibel wiederverwendbare Informationsstruktur („Template”) zu entwickeln.
Das Vorbild war Volere [Vol], ein Template für Software-Requirements, das sich flexibel in beliebigen Entwicklungsprojekten zur Kommunikation und Dokumentation von Anforderungen (== dem Problemraum) einsetzen lässt. Peter und Gernot haben mit arc42 das Pendant für den Lösungsraum (== die Architektur) entwickelt. Von Beginn an stand das Vorhaben unter der Prämisse, arc42 komplett Open Source (siehe [GitHarc42]) zu entwickeln und frei verfügbar anzubieten.
Ach ja, 42: Die etwas ältere Generation von Softwerkern mag den schrulligen britischen Science-Fiction-Autor Douglas Adams noch kennen, Douglas hat „Per Anhalter durch die Galaxis” [Wiki] geschrieben, in dem die Zahl 42 als die Antwort auf die „Ultimative Frage des Lebens, des Universums und dem ganzen Rest“ erscheint. arc42 soll für Ihre Systeme und Softwarearchitekturen die Antworten zumindest auf viele Fragen bezüglich Architektur- und Lösungsentscheidungen bereithalten.
Der Architektur-Schrank
Vergleichen Sie arc42 mit einem Schubladenschrank: Die Schubladen sind ordentlich beschriftet und enthalten zusammengehörige Informationen. arc42 enthält zwölf solche Fächer (s. Abb. 1). Die Bedeutung dieser arc42-Fächer ist leicht verständlich.
arc42 gibt Ihnen damit eine einfache, klare Struktur zur Beschreibung Ihrer (komplexen!) Systeme. Beginnend bei den Zielen und Anforderungen an Ihr System und die Einbettung in die fachliche und technische Umgebung, können Sie nahezu alle Beteiligten oder Interessenten Ihres Systems mit passenden Informationen zur Architektur versorgen.
arc42 ist auf Verständlichkeit optimiert: Es leitet Sie auf ganz natürliche Weise an, jede Art von Architekturinformation und -entscheidung in einem verständlichen und nachvollziehbaren Zusammenhang zu erklären. Anwenderinnen und Anwender von arc42 loben die Verständlichkeit der Ergebnisse, die aus diesem etablierten Aufbau resultiert. Entwicklungsteams freuen sich über den überschaubaren Aufwand, den sie für Erstellung und Pflege ihrer Architekturdokumentation benötigen.
Abbildung 1 zeigt den Aufbau von arc42 im Überblick.
Abb. 1: Zwölf Schubladen für alle Informationen
Sparsam und gründlich
Gleichzeitig ermöglicht arc42 sparsame Dokumentation, das heißt, es fügt sich für Entwicklungsteams nahtlos in deren gewohnten Arbeitsprozess ein. Wir nennen das gerne „prozess-agnostisch”, arc42 funktioniert für iterativ-inkrementelle Prozesse ebenso gut wie für andere Organisationsformen. Teams können zu jedem Zeitpunkt die Informationen kommunizieren oder dokumentieren, an denen sie ohnehin gerade arbeiten. Hier greift die Schrank-Metapher von arc42: Auch Ihrem privaten Kleider- oder Küchenschrank ist es ja völlig egal, in welcher Reihenfolge Sie die Fächer ein- oder ausräumen.
Damit stellt arc42 Entwicklungsteams auch frei, welche Teile des Templates sie überhaupt verwenden (weiter unten habe ich ein paar Vorschläge, was Sie auf jeden Fall nutzen sollten.)
Abb. 2: Tipps und in Doku integrierte Beispiele
Werkzeug-agnostisch
Sie können Ihre arc42 Architekturdokumentation mit Markdown oder AsciiDoc schreiben, mit Microsoft-Word©, in einem Wiki oder auch in einem der Modellierungswerkzeuge. Für die meisten dieser Werkzeuge liefert arc42 out-of-the-box eine passende Version vorgefertigt, für andere Werkzeuge können Sie die ganz leicht übernehmen. Aus diesem Grund nennen wir arc42 „werkzeug-agnostisch”.
Ich selbst schreibe Dokumentation einiger Open-Source-Projekte auf Basis von AsciiDoc, Diagramme erstelle ich gerne mit diagrams.net [diagrams] und PlantUML [PlantUML]. Wenn es etwa im kommerziellen Umfeld etwas exakter werden muss, kombiniere ich AsciiDoc oder ein Wiki auch schon mal mit einem UML-Werkzeug. Für arc42 selbst spielt das verwendete Werkzeug keinerlei Rolle! Große Unterschiede liegen natürlich in den technischen oder darstellerischen Möglichkeiten der Tools. Das allerdings ist eine längere Geschichte, auf die ich an dieser Stelle nicht weiter eingehen möchte.
Stakeholder abholen!
Die einzelnen Teile von arc42 erleichtern es ungemein, nahezu beliebige Stakeholder abzuholen: arc42 beginnt in Abschnitt 1 mit einem Überblick der wesentlichen Anforderungen – der ja hoffentlich in der Requirements-Dokumentation ebenfalls zu finden ist, sofern es überhaupt solch eine Doku gibt. Mit diesen zentralen Anforderungen, insbesondere Business-Zielen und Qualitätsanforderungen, können Leserinnen und Leser die nachfolgenden Architekturentscheidungen viel besser verstehen!
Beispiele?
Für ein aussagekräftiges Beispiel genügt der Platz in diesem Artikel leider nicht. Aber es gibt eine Menge Abhilfe für alle, die lieber auf Beispiele schauen:
- Erstens enthält die aktuelle Dokumentation zu arc42 (siehe [arc-42Doc]) zu jeder Sektion seit Neuestem jeweils einige Beispiele.
- Zweitens gibt es mehrere Bücher mit kompletten Real-World-Beispielen, etwa [StMÜSiZö] (für Leser dieses Artikels stark vergünstigt) und [HrKoRei] (für Embedded-Systeme).
Alles optional!
„Ein Dutzend Bestandteile”, fragen sich einige bestimmt, „brauche ich denn wirklich so viel?” arc42 ist als Repository (oder, bildlich gesprochen, als Schrank) gedacht. Sie sollen die für Sie relevanten, wichtigen oder speziellen Informationen dort ablegen („dokumentieren”). Ein typischer Anfängerfehler: arc42 von Teil 1 bis 12 wie ein Formular ausfüllen!
Wie oben bereits angedeutet, sollten Sie das geschickter anstellen: Konzentrieren Sie sich auf die für Ihr System wesentlichen Bestandteile. Im Extremfall hat Ihre arc42-Dokumentation dann halt nur wenige Bestandteile. Ein paar Themen sollten Sie jedoch für jede Art von System beschreiben – meine persönliche Hitparade sieht dabei wie folgt aus:
- Top-5-Qualitätsanforderungen, in Form konkreter Szenarien (arc42 Sektion 1.2).
- Externe Schnittstellen, als Kontextdiagramm oder Tabelle (arc42 Sektion 3).
- Wesentliche, fundamentale Lösungsentscheidungen. 2 bis 5 kurze Absätze (arc42 Sektion 4).
- Bausteinsicht Ebene 1 (Top-Level-Zerlegung des Systems) (arc42 Sektion 5.1).
- Die wesentlichen 2 bis 5 querschnittlichen oder technischen Konzepte (arc42 Sektion 8).
Schon besser, oder? Nur noch 5 Teile, die ich Ihnen in jedem Fall abverlangen möchte. (Ich garantiere Ihnen, wenn Sie meinen arc42-Kollegen Peter Hruschka fragen, bekommen Sie mehr als diese fünf kleinen Hausaufgaben!)
arc42 und C4
Der umtriebige Softwarearchitekt Simon Brown hat mit seinem C4-Modell [C4] eine international sehr verbreitete Vorgehensweise plus Notation für die Dokumentation wichtiger Teile von Softwarearchitekturen geschaffen. Für C4 gibt sogar unterstützende Tools – wie hängt das mit arc42 zusammen?
Für Wortspiele sensible Leser werden bemerkt haben, dass C4 ja sozusagen ein integraler Bestandteil von ar-C4-2 ist … Spaß beiseite: C4 und arc42 ergänzen sich großartig – bestätigt Simon Brown auch auf seiner Website.
C4 steht für Context, Container, Component and Class. Vorsicht: C4 versteht unter „Container” etwas komplett anderes, als Sie das vielleicht in Ihrem modernen Cloud-Umfeld erwarten. Schauen Sie in Tabelle 1 – dort finden Sie die Gegenüberstellung von C4-Konstrukten mit den passenden Teilen von arc42.
Was bei genauerem Vergleich auffällt: C4 lässt aus dem Default sowohl technische Infrastruktur, Laufzeitsicht, die querschnittlichen Konzepte sowie die Architekturentscheidungen heraus. Diese Teile zählen für Simon Brown zu den supplementary diagrams. Insgesamt können Sie C4 und arc42 hervorragend kombinieren!
| C4-Begriff | Entsprechung in arc42 |
|---|---|
| (System) Context | (fachliche) Kontextabgrenzung |
| Container | Bausteinsicht Ebene 1, die Top-Level-Zerlegung des Systems |
| Components | Bausteinsicht Ebene 2 |
| Classes | Bausteinsicht, noch tiefere Ebene(n). So detailliert wollen wir in arc42 nur selten werden |
Was bringt die Version 8?
Gute Nachrichten für alle, die bereits arc42 einsetzen: In Version 8 gibt es keine (!) Änderungen an der Struktur des Templates. Strukturell bleibt also alles beim Alten.
Interessante Ergänzungen stecken in Details, insbesondere bei den Querschnittskonzepten (Sektion 8) und Architekturentscheidungen (Sektion 9). Weiter unten gehe ich kurz auf diese Neuerungen ein.
Daneben wurde für das Update auf V8 die Dokumentation von arc42 selbst an einigen Stellen deutlich erweitert und aktualisiert:
- Die ohnehin schon recht umfangreiche Website docs.arc42.org enthält jetzt Beispiele für sämtliche Teile von arc42, übernommen aus der Architekturdokumentation realer Systeme.
- Bei den „Architekturentscheidungen” (Sektion 9) rücken die Architecture Decision Records (ADR) stärker in den Vordergrund. Sie finden jetzt konkrete Vorschläge, um Ihre Entscheidungen strukturiert und effektiv festzuhalten.
- Den Querschnittskonzepten (Sektion 8) haben wir in der Dokumentation ebenfalls mehr Raum gegeben.
- Alle Teile von arc42 enthalten (optionale) Hilfetexte, die jeweils den gewünschten Inhalt vorstellen und dessen Motivation erklären. Ebenfalls unterbreitet arc42 jeweils Vorschläge für die mögliche Form der jeweiligen Informationen. Neu hinzu kommen spezifische Querverweise in die teilweise sehr ausführliche Dokumentation. An jeder Stelle des Templates können Anwender jetzt also zu weitergehenden Erläuterungen, Tipps und Ratschlägen springen, oder sich direkt passende Beispiele anschauen.Insbesondere dieser letzte Punkt (in Doku integrierte Beispiele) soll neuen Anwendern helfen, mit ihrer eigenen Dokumentation noch schneller und einfacher loslegen zu können.
Schauen wir uns die beiden Punkte etwas genauer an, die in V8 stärker in den Fokus rücken.
Architekturentscheidungen mit ADRs
Ich habe Entwicklungsteams erlebt, die ihre Entscheidungen ausschließlich in Meeting-Protokollen festgehalten haben. Nach wenigen Wochen hatte niemand mehr den Überblick, welche Entscheidungen noch gelten, geschweige denn, warum so entschieden wurde.
Vermeiden Sie diese Falle: Nutzen Sie eine leichtgewichtige Struktur (Architecture Decision Record, siehe [ADR] und [GitHADR]), um ihre wesentlichen Entscheidungen zu dokumentieren. Das kann in einer Art Blog, umgekehrt chronologisch geordnet, erfolgen. Entscheidungen mit Architekturrelevanz verlinken Sie einfach in Ihrem arc42 – fertig.
Tabelle 2 zeigt die einfache Struktur von ADRs nach dem Vorschlag von Michael Nygard [ADR].
| Abschnitt | Bedeutung |
|---|---|
| Titel | Wie wollen wir diese Entscheidung nennen? |
| Status | Welchen Status hat diese Entscheidung (vorgeschlagen, angenommen, abgelehnt, deprecated, veraltet)? |
| Kontext | Welches Problem lösen wir damit, was motiviert diese Entscheidung? |
| Entscheidung | Was entscheiden wir, was soll getan/geändert werden? |
| Konsequenzen | Was wird durch diese Entscheidung einfacher und was schwieriger? |
Querschnittliche Konzepte
Einige Themen innerhalb von Systemen betreffen oft mehrere Bausteine, Komponenten oder Elemente. Es könnte einfacher sein, solche Querschnittsthemen an einer zentralen Stelle zu kommunizieren oder zu dokumentieren, anstatt sie in der Beschreibung der betroffenen Elemente zu wiederholen.
Bestimmte Konzepte können alle Elemente eines Systems betreffen, andere sind vielleicht nur für einige wenige relevant. Im Beispiel von Abbildung 3 betrifft das Logging alle drei Komponenten, während die Security nur für zwei Komponenten relevant ist.
Einige Beispiele aus der Praxis:
- Innerhalb eines Systems wird ein gemeinsames Format für Log-Nachrichten festgelegt, kombiniert mit einer gemeinsamen Konvention für die Wahl der geeigneten Log-Destination. Diese Entscheidungen könnten zusammen mit Implementierungsbeispielen als „Logging-Konzept” beschrieben werden.
- Ein System verfügt über zahlreiche Backend-Dienste, die untereinander auf der Grundlage von Remote Procedure Calls oder http-basiertem REST kommunizieren. Die aufrufenden Dienste („Consumer”) müssen sich immer gegenüber dem aufgerufenen Dienst („Provider”) authentifizieren. Für diese Authentifizierung soll ein zentraler, gemeinsamer Dienst genutzt werden. Die technischen und organisatorischen Details einer solchen
- Authentifizierung können als „Backend-Authentifizierungskonzept” beschrieben werden.
Abb. 3: Querschnittliche Konzepte (schematisch)
Damit soll es bezüglich inhaltlicher Aspekte an dieser Stelle genug sein.
Here to stay
Falls Sie oder Ihr Management befürchten, arc42 könne aus der Mode kommen, wie so manche der ehemals coolen technischen Frame-
works: arc42 gibt es seit 2005, und es wird mittlerweile von vielen Unternehmen und Organisationen weltweit eingesetzt, wobei der Schwerpunkt im europäischen Raum liegt.
Seit etwa 2012 ist die Top-Level-Struktur von arc42 stabil, bei einem Framework könnte man sagen: „Die API ist stabil geblieben”. Seien Sie also beruhigt – wenn Sie Ihre Dokumentation auf Basis arc42 erstellen, haben Sie damit in eine nachhaltige Methodik investiert. Vermutlich leben Struktur und Methodik von arc42 länger als ihr aktuell eingesetztes Modellierungs- oder Dokumentationswerkzeug :-) Zu arc42 gibt es mittlerweile eine Fülle von Blogposts, Podcasts, Videos und Büchern.
Weiter Informationen
[ADR] Architecture Decision Records - das Original von M. Nygard, https://cognitect.com/blog/2011/11/15/documentingarchitecture-decisions
[arc42] Downloads und Einstieg https://arc42.org
[arc42Doc] arc42-Dokumentation, https://docs.arc42.org
[C4] C4-Model von S. Brown, https://c4model.com/
[diagrams] diagrams.net, vormals draw.io, leistungsfähiges und multi-plattform-fähiges Grafikwerkzeug, https://diagrams.net
[FAQ] 132 frequently asked questions on arc42, https://faq.arc42.org
[GitHADR] Sammlung von ADRs bei GitHub, https://adr.github.io/
[GitHarc42] arc42 bei GitHub, https://github.com/arc42
[HrKoRei] P. Hruschka, I. Kostov, W. Reimesch, arc42 by Example, Volume-2 (Embedded Systems), https://leanpub.com/arc42byexample-volume
[PlantUML] Diagramme mithilfe einer textuellen DSL beschreiben und automatisiert rendern lassen, https://plantuml.com
[StMÜSiZö] G. Starke, R. D. Müller, M. Simons, St. Zörner, arc42 by Example, eBook bei Leanpub (Für Leser vom JavaSPEKTRUM mehr als 75% günstiger als der Originalpreis), https://leanpub.com/arc42byexample/c/v8-javaspektrum
[Vol] Volere Template für Requirements, https://www.volere.org/
[Wiki] https://de.wikipedia.org/wiki/Per_Anhalter_durch_die_Galaxis_(Romanreihe)
