Architectural Decision Records

Architecture is abstract until operationalized, when it becomes a living thing.

Patrick Kua

Das agile Manifest für Software-Entwicklung hat die Dokumentation nicht ohne Grund auf die rechte Seite gestellt: „Working software over comprehensive documentation.“

Eine leichtgewichtige und daher schnelle Dokumentation ermöglicht die agile Praxis der Architectural Decisions Records.

Woher kommen Architectural Decision Records (ADR)?

Die Architectural Decision Records entstammen der agilen Praxis der evolutionären Architektur. Bei der „Evolutionary architecture“ handelt es sich um einen Architektur-Ansatz, in dem die Veränderbarkeit von Software mitgedacht wird.

Evolutionäre Architekturen tragen zunächst einmal der Erkenntnis Rechnung, dass Software in inkrementellen Schritten entsteht als auch Anpassung, Weiterentwicklung und sogar Wandel auf mehreren Dimensionen unterstützen soll: 

• Dimension technische Ebene
  Neue Sprachen, Frameworks, Libraries und Operating Environments
• Dimension fachliche Ebene (Business)
  Änderungen des Marktes, neue Geschäfts-/Einkommensmodelle, verändertes Konsumverhalten, neue Wettbewerbssituation

Um evolutionäre Architektur zu ermöglichen, sind Fähigkeiten wie CI/CD, Testautomatisierung und DevOps erforderlich. Darüber hinaus ist auch eine gemeinsame Entscheidungs-Kultur zwischen Architekten und Devs erforderlich. Mehr dazu findet man in Kevin Hickeys Artikel The Role of an Enterprise Architect in a Lean Enterprise.

Zudem sollen Prinzipien wie „Verwerfbarkeit von Entscheidungen“, „Vermeidung von Prematurity“ und die „Vertagung von Entscheidungen auf den letztmöglichen (verantwortungsvollen) Zeitpunkt“ im Blick behalten werden.

ADRs gehen auf eine Idee von Michael Nygard aus dem Jahr 2011 zurück. Thought Works platziert die Methode von Architectural Decision Records im November 2016 auf Trial und im November 2017 auf Adopt. 

Heißt: ADRs haben es tatsächlich in den Mainstream geschafft.

Was sind Architectural Decision Records?

Eine Architekturentscheidung (Architectural Decision) ist eine Softwaredesignentscheidung, die eine funktionale oder nicht-funktionale Anforderung betrifft, die architektonisch bedeutsam ist. 

Eine architektonisch bedeutsame Anforderung ist eine Anforderung, die eine messbare Auswirkung auf die Architektur und Qualität eines Softwaresystems hat.

In einer Welt der evolutionären Architektur ist es besonders wichtig, Designentscheidungen zur Nachvollziehbarkeit für künftige Teammitglieder sowie zur Transparenz für weitere Stakeholder aufzuzeichnen.

Genau hier greift die agile Praxis der ADRs! Es ist eine Technik, um wichtige Architekturentscheidungen zusammen mit ihrem Kontext (also inklusive aller vorliegenden Informationen) und ihren Konsequenzen festzuhalten. 

Die Motivation hinter den bisherigen Entscheidungen ist so für jeden sichtbar; gegenwärtig und zukünftig. Mit der Zeit werden vorherige Entscheidungen geändert oder sogar revidiert und die Änderungen werden im Kontext des Verlaufs deutlich.

Das ermöglicht Nachverfolgbarkeit und zeigt auf, welche Trade-offs zu welchen Zeitpunkten gemacht wurden und warum.

Wie funktionieren ADR?

Das Template für Architectural Decision Records ist sehr einfach aufgebaut und strukturiert. Jeder ADR setzt sich aus den folgenden Abschnitten zusammen:

• Titel (title):
  • Kurze, den Inhalt des ADR wiedergebende Beschreibung der Entscheidung.
  • Beispiel:
  • ADR 1: Deployment on Ruby on Rails 3.0.10″ oder „ADR 9: LDAP for Multitenant Integration“
• Kontext (context):
  • Beschreibung der Bedingungen, die zu der Entscheidung geführt haben. 
  • Beschreibt die Kräfte/Einflussfaktoren, die im Spiel sind; darunter technologische, politische, soziale und projektspezifische. Diese Kräfte stehen wahrscheinlich in einem Spannungsverhältnis und sollten als solche benannt werden. Die Sprache in diesem Abschnitt ist wertneutral, es werden lediglich Fakten beschrieben.
  • Zählt auch die zur Verfügung stehenden Optionen auf. 
• Entscheidung (decision):
  • Beschreibung der Entscheidung, die im Rahmen des vorher beschriebenen Kontexts erfolgt ist. 
• Status (status):
  • Position im Lebenszyklus der Entscheidung wie „proposed“, „accepted“, „discarded“, „deprecated“ oder „superseded“.
• Konsequenzen (consequences):
  • Auflistung aller positiven und negativen Konsequenzen.
  • Metriken der Architectural Fitness Function können aufgenommen werden. 

Ein Video findet ihr hier:

Achtung, YouTube!

Datenschutz ist uns wichtig! Daher müssen wir noch kurz etwas los werden … Um das Video direkt auf dieser Seite angezeigt zu bekommen, musst Du leider folgende Cookies akzeptieren: statistik, Marketing.

Welche Praxistipps können wir Euch mitgeben?

Natürlich nutzen auch wir die Architectural Decision Records. Im Zuge dessen haben wir ein paar Praxistipps herausarbeiten können, die ich euch gerne mitgeben möchte.

Tipp 1: 1 ADR = 1 Entscheidung 

Bitte legt nur eine Entscheidung pro Architectural Decision Record ab. Diese sollte maximal zwei Seiten lang sein.

Tipp 2: Single Source of Truth

Es darf nur eine „Source of truth“ geben. Eine zentrale Ablage der Entscheidung gewährleistet Nachverfolgbarkeit und Nachvollziehbarkeit.

Es wird empfohlen, die Architectural Decision Records in der Versionsverwaltung zu speichern, anstatt in einem Wiki, da sie dann potentiell eine höhere Chance haben, mit dem Code synchron zu bleiben.

Tipp 3: Nummerierung der ADRs

ADRs werden fortlaufend nummeriert. Die Nummern werden nicht wiederverwendet.

Wenn eine Entscheidung rückgängig gemacht wird, wird die vorherige Entscheidung beibehalten, aber als „ersetzt“ markiert. Es ist immer noch relevant zu wissen, dass es diese Entscheidung gab, aber es nun nicht mehr eine adäquate Entscheidung ist.

Tipp 4: Gegenlesen von unbeteiligtem Dritten

Optimalerweise liest ein unbeteiligter Reviewer, der nicht an der Entscheidung mitgewirkt hat, die fünf „W“-Fragen: Wann? Wer? Warum? Wozu? Was? aus den ADR heraus.

In einem kurzen Double-Check prüft ihr so, ob die Nachvollziehbarkeit und Verständlichkeit gewährleistet ist. Nur dann ist der eigentliche Zweck der Doku erfüllt.

Tipp 5: Tooling

Es gibt einige ADR-Tools, die ich euch ebenfallst nicht vorenthalten möchte:

• adr.github.io
  Die Homepage der ADR GitHub-Organisation mit umfangreicher Dokumentation und Tool-Tipps
• ADR-Tools
  Ein CLI-Tool, das die Arbeit mit ADR vereinfacht

tl;dr

Architectural Decision Records sind eine Technik, mit der wichtige Architekturentscheidungen inklusive Kontext und Konsequenzen dokumentiert werden.

Was denkt Ihr, ist das hilfreich für Euch? Welche Doku-Formen nutzt ihr in euren Projekten, um eure Architekturntscheidungen festzuhalten?