Haben Sie King Kong vs. Godzilla gesehen? Oder Alien vs. Predator (Teile 1 und 2)? Oder Dracula vs. Frankenstein (Deutscher Titel: „Draculas Bluthochzeit mit Frankenstein“)? Dieser Beitrag liefert etwas sehr Ähnliches: nur ohne Monster.

arc42_vs_Godzilla

arc42 vs. …  ja gegen was eigentlich? Oder ist arc42 etwa alternativlos?

arc42 – Dokumentionsvorlage der Herzen

Einblicke in Projekte und Rückmeldungen auf Konferenzen zeigen: arc42, der Dokumentationsvorschlag für Softwarearchitektur, hat sich zumindest im deutschsprachigen Raum zu einer Art De-Facto-Standard entwickelt.

Für die hohe Bekanntheit und Verbreitung gibt es unterschiedliche Gründe, ganz unabhängig davon, ob arc42 nun tatsächlich „pragmatisch, praktisch, gut“ ist oder nicht:

  • Die Tatsache, dass arc42 frei verfügbar ist.
  • Die zunehmende Anzahl CPSA-Zertifizierter nach iSAQB (CPSA == Certified Professional for Software Architecture). Der iSAQB nennt in seinen Lehrplänen arc42 als eine Option, Softwarearchitektur zu beschreiben.
  • Das auflagenstarke Buch „Effektive Softwarearchitekturen“ von Gernot Starke. Gernot ist (Mit-)Gründer von arc42, sein Buch behandelt natürlich auch den Gliederungsvorschlag.

Gleichwohl kommen regelmäßig – beispielweise bei flächendeckenden Einführungen von arc42 in großen Unternehmen – immer wieder Fragen in zwei Richtungen auf:

  1. Warum nehmen wir arc42? Was spricht dafür?
  2. Gibt es Alternativen zu arc42? Wenn ja, welche? Wie unterscheidet sich arc42 von diesen?

Die zweite Frage ist insbesondere dort anzutreffen, wo Dokumentation in Englisch verfasst wird, ggf. sogar gemeinsam mit z.B. amerikanischen Kollegen oder Kooperationspartnern. Anders als in D-A-CH, ist arc42 trotz verfügbarer englischer Übersetzung z.B. in Amerika wenig bekannt.

In diesem Blog-Beitrag stelle ich eine interessante Alternative zu arc42 vor und vergleiche die beiden Ansätze miteinander. Damit können Sie zumindest die Frage „Gibt es Alternativen“ bereits mit „ja“ beantworten und für diese Alternative hätten Sie Unterschiede und Gemeinsamkeiten parat. Letztere überwiegen (Spoiler-Alarm).

Alternativen. Wozu?

Um die Frage zu beantworten, ob es Alternativen zu X gibt, muss zunächst geklärt werden, was genau X ist. Viele Leute draußen im Feld setzen arc42 mit dem Wordtemplate gleich („arc42? Kenn ich. Da muss man dieses Word-Dokument ausfüllen“). Wohlwollendere sehen in arc42 eine Herangehensweise, um Softwarearchitektur methodisch zu entwickeln, und das Template ist „nur“ die Ablagestruktur für Arbeitsergebnisse. Also eine Art Vorgehensmodell für Architekturentwurf.

Ich selbst sehe in arc42 in erster Linie einen Vorschlag, um Architekturbeschreibungen, ganz gleich ob Vortrag, Foliensatz oder Dokument, zu gliedern. Eine Art Ablagesystem für Zutaten einer Architekturdokumentation inkl. einer sinnvollen (Lese-)Reihenfolge. Wobei bei Weitem nicht immer alle Elemente der Gliederung (immerhin 12 Kapitel, siehe Abb. 1) benötigt werden.

Gliederung nach arc42

Abb. 1: Gliederung einer Architekturbeschreibung nach arc42

Nichts als die halbe Wahrheit

In Projekten und Workshops höre ich immer wieder das Argument „Der Code ist die beste Dokumentation“. Meist von Entwicklern. Ich könnte den Leuten unterstellen, dass sie zu faul zum Dokumentieren sind. Stattdessen ist hier der Hinweis angebracht, dass der Code – obschon er wertvolle Informationen trägt – nicht die ganze Geschichte erzählt. Die bloße Verwendung einer bestimmten Technologie („Wir benutzen das Spring Framework“) beispielsweise, brauche ich tatsächlich nicht dokumentieren. Das sehe ich der Lösung in der Regel an. Was ich widerum der Lösung nicht ansehe: Warum benutzen wir (immer noch) das Spring Framework? Hatten wir Alternativen erwogen? Welche Kriterien haben wir zur Entscheidung herangezogen? Oder war es eine Randbedingung?

„The code doesn’t tell the whole story.“

Simon Brown in  „Software Architecture for Developers“

Genau hier setzt Simon Brown mit dem Buch „Software Architecture for Developers“ an. Sein Ansatz ist sehr pragmatisch, spricht Entwickler an, und ist auch im englischsprachigen Raum gut vorzeigbar. Simon Brown schlägt in seinem Buch Dinge vor, die den Quelltext um wichtige Informationen ergänzen. Die folgende Abbildung zeigt seine „Zutaten“ im Überblick:

GuidebookGliederung

Abb. 2: Zutaten nach „Software Architecture vor Developers“ (Simon Brown)

 

Das Ganze fasst Simon Brown in Anlehnung an einen Reiseführer als Software Guidebook zusammen. Das Ergebnis ist ebenfalls ein Gliederungsvorschlag für Architekturbeschreibungen. Mithin ein interessanter Kombattant für arc42 …

Simon Brown: Software Architecture for Developers

Simon Brown: Software Architecture for Developers. https://leanpub.com.

Software Guidebook, Table of Contents

  1. Context (*)
  2. Functional Overview (*)
  3. Quality Attributes (*)
  4. Constraints (*)
  5. Principles (*)
  6. Software Architecture (*)
  7. External Interfaces
  8. Code
  9. Data
  10. Infrastructure Architecture (*)
  11. Deployment (*)
  12. Operation and Support (*)
  13. Decision Log

Dabei schätzt Simon Brown die Zutaten als unterschiedlich wichtig ein. Dinge, die er laut eigener Aussage niemals weglässt, sind oben in der Liste mit (*) markiert.

Mapping vom Software Guidebook auf arc42

Finden sich die von Simon Brown vorgeschlagenen Elemente in der Struktur von arc42 wieder? Ja, sie tun. Die folgende Tabelle gibt für jedes Kapitel aus dem Software Guidebook einen passenden Ort in arc42 an (Alternativen in Klammern).

MappingGuidebookArc42

Abb. 3: Ein Mapping vom Software Guidebook auf arc42

In vielen Punkten liegen direkte Entsprechungen vor (Beispiele: Constraints/Randbedingungen, Context/Systemkontext). An anderen Stellen gehört für eine Zuordnung ein bisschen methodischen Wissen und Kenntnis der beiden Ansätze dazu. So lassen sich Architekturprinzipien in arc42 meiner Erfahrung nach am besten in der Lösungsstrategie (Abschnitt 4.) unterbringen. Nüchtern betrachtet sind die beiden Ansätze allerdings recht ähnlich. Ein Mapping in anderer Richtung (arc42-Schnipsel im Guidebook von Simon Brown „abheften“) ist ebenso möglich.

Was sind die Unterschiede?

Bei vielen Zutaten lassen sich also „Orte“ in der jeweils anderen Gliederung finden. So gesehen, sind die Unterschiede gar nicht groß und liegen eher in den Ansätzen selbst. Ich nenne zwei konkrete Beispiele: Sichten und Qualitätsszenarien.

arc42 ist von klassischer Softwarearchitektur inspiriert und beinhaltet in guter Tradition zu IEEE 1471 verschiedene Sichten (Englisch: „Views“): Bausteinsicht, Laufzeitsicht, etc. Simon Brown hingegen strapaziert den Sichtenbegriff nicht sonderlich – im Gegenteil (eine Kapitelüberschrift bei ihm: Beware of the “views”). Er schlägt aber auch Diagramme zur Visualisierung bestimmter Aspekte vor und kritisiert vor allem dogmatische Diskussionen nach dem Motto: „Was gehört in welche Sicht?“.

Qualitätsszenarien (Synonym: Bewertungsszenarien) als Konkretisierung von Qualitätszielen haben in arc42 einen festen Platz. Dabei handelt es sich, wie bei den Sichten um ein klassisches Werkzeug der methodischen Softwarearchitektur. Hier konkret der qualitativen Architekturbewertung. Simon Brown verbietet keine Qualitätsszenarien, legt diese aber auch nicht nahe und erwähnt sie auch nicht. Am ehesten passt dieses Element im Guidebook bei den „Qualitity Attributes“. Und da tue ich es auch hin, wenn ich das Guidebook als Struktur in Projekten verwende.

Fazit

Beide gezeigten Ansätze zur Dokumentation geben gute Hinweise, welche Aspekte Ihrer Softwarearchitektur Sie festhalten sollten, um die Lösung (auch später noch) kommunizieren zu können. Beide Vorschläge müssen Sie auf Ihre Projektsituation anpassen. Insbesondere, wenn es sich nicht um ein Informationssystem im klassischen Sinne handelt, sondern stattdessen um eine Systemlandschaft, eine Produktfamilie oder ein eingebettetes System.

Dokumentation ist kein Selbstzweck. Das eigentliche Ziel, die Lösung nachvollziehbar festzuhalten, lässt sich mit arc42 ebenso wie mit dem Software Guidebook erreichen. Die große Überdeckung der beiden Ansätze lässt vermuten, dass ähnliches Erfahrungswissen dahintersteckt. Nutzen Sie es zumindest als Inspiration und Anregung, bevor Sie sich eigene Inhalte und eine völlig neue Gliederung für Ihre Softwarearchitekturbeschreibung ausdenken!

Weitere Informationen

  • „alternativlos“ war das Unwort des Jahres 2010. Zitat aus der Begründung: „Das Wort suggeriert sachlich unangemessen, dass es bei einem Entscheidungsprozess von vorn-herein keine Alternativen und damit auch keine Notwendigkeit der Diskussion und Argumentation gebe.“
  • Die Struktur von arc42 wird auf einer Seite der zugehörigen Homepage prägnant dargestellt.
  • Das Buch „Software Architecture for Developers“ von Simon Brown ist bei Leanpub erschienen.
  • Meine arc42-Starschnitt Serie hier im Blog stellt Schnipsel für Schnipsel eine Zutat  zur Architekturbeschreibung vor, demonstriert sie anhand eines durchgängigen Beispiels und „heftet“ sie in arc42 ab.
  • IEEE 1471 ist ein Standard zur Beschreibung von Softwarearchitektur (siehe Wikipedia)
  • In meinem Buch Softwarearchitekturen dokumentieren und kommunizieren schlage ich ein Herangehen vor, um Zutaten anhand von Zielgruppen auszuwählen und zu (re-)kombinieren.