Architecture Decision Records

14. Nov 2022

Page content

Während Software entwickelt oder geplant wird, stellen sich diverse Fragen und es werden Entscheidungen getroffen. Oft gibt es das Problem, dass nach vielen Jahren (oder durch einen Wechsel der Entwickler) die ursprüngliche Entscheidung nicht mehr nachvollziehbar oder verständlich ist.

Architecture Decision Records (ADR) sind eine Möglichkeit, um diese Entscheidungen kurz und prägnant zu dokumentieren.

Ursprungsfragen könnten sein:

Welche Datenbank benutzen wir?
Wie verbinden wir die Systeme/Anwendungen miteinander?
Wie und wo legen wir Programmeinstellungen ab?
Wo stellen wir die Anwendung bereit?
Wie loggt die Anwendung?
Was setzen wir mit Framework XYZ um?
Wie speichern wir ein Datum?

Es kann sein, dass nicht jede Frage für einen ADR geeignet ist. In vielen Fällen gibt es auch eine Richtlinie (Coding Guidelines) im Unternehmen oder der Abteilung, sodass einige Fragen zentral dokumentiert sind.

Bei den o.g. Fragen geht es mir um einige Beispielfragen, welche bei einem Teamwechsel, neuen Mitarbeitern oder Bearbeiten alter Projekte auftreten können.

Ziel eines ADR

Das Ziel (bzw. die Aufgabe) eines ADR ist es, kurz und prägnant eine Entscheidung, den Kontext und die Konsequenzen zu dokumentieren. Es wurde eine Entscheidung getroffen, welche die Architektur einer Anwendung beeinflusst. Diese Entscheidung sollte nachvollziehbar und vor allem auffindbar sein.

Aus eigener Erfahrung gibt es immer wieder den Punkt, wo sich Fragen ergeben und niemand (oder nur ein einziger) eine Antwort darauf hat. Teilweise habe ich es schon erlebt, dass eine Anwendung modernisiert und ein zentraler Baustein ausgetauscht wurde. Nach mehreren Wochen Arbeit ergibt sich eine Stelle, die man nicht tauschen kann, wodurch die investierte Zeit und Arbeit wieder rückgängig gemacht werden muss.

Hätte man bei solchen Stellen gewusst, warum etwas so umgesetzt wurde, dann erspart das oft Aufwand und Zeit. Hierbei bitte nicht vergessen, dass auch ein Kommentar innerhalb einer Klasse oder im Kopfbereich sinnvoll sein kann oder in der allgemeinen Architekturdokumentation des Projekts.

Struktur eines ADR

Der Aufbau eines ADR ist schnell erklärt. Als Beispiel nutze ich adr-tools. ADRs werden üblicherweise in Markdown geschrieben.

# 1. Titel meines ADR

Date: 2022-11-06

## Status

Accepted

## Context

The issue motivating this decision, and any context that influences or constrains the decision.

## Decision

The change that we're proposing or have agreed to implement.

## Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

Einen Industriestandard für ADRs habe ich nicht gefunden. Allgemein sind folgende Felder zwingend erforderlich, damit ein ADR seinen Zweck erfüllt:

Title
Date
Context
Decision
Consequences

In einem Projekt habe ich in den ADRs eine zusätzliche Überschrift gefunden: Alternatives. Der Bereich wurde explizit dazu genutzt, alternative Lösungen oder Frameworks zu beleuchten. In der Regel wurden hier wichtige Punkte genannt, warum etwas nicht genutzt werden kann oder wo (große) Nachteile liegen.

Persönlich finde ich den Punkt “Alternatives” sehr praktisch. Es gibt oft mehrere Wege zu einer Lösung aber nicht jeder Weg kann alles abdecken oder hat Nachteile. In diesem Bereich wird die implizite Entscheidung gegen eine alternative Lösung transparent dokumentiert, was der Nachvollziehbarkeit zugute kommt.

Beispiel: Datum in UTC-Format speichern

Um einen ADR etwas greifbarer zu machen, findet ihr nachfolgend einen beispielhaften ADR. Die getroffene Entscheidung lautet Zeitstempel werden im UTC Format in der Datenbank gespeichert.

# 1. Zeitstempel werden im UTC Format in der Datenbank gespeichert

Date: 2022-11-01

## Status

Accepted

## Context

Die Anwendung speichert Daten wie 'CreateDate' oder 'UpdateDate' und hat globale Nutzer, denen
diese Werte angezeigt werden. Um mögliche Probleme oder Abweichungen durch lokale Zeiten
zu vermeiden, speichern wir die Daten in einem einheitlichen Format.
Zudem haben wir eine verteilte Datenbank, deren Server in unterschiedlichen Ländern
und Zeitzonen stehen.

## Decision

Die Daten und Zeitstempel werden im UTC-Format in der Datenbank gespeichert. Dabei muss
die Anwendung die richtigen Zeitstempel setzen bzw. an die Datenbank übergeben.
Durch das UTC-Format vermeiden wir Fehler, die durch die globale Nutzung und unterschiedliche
Zeitzonen auftreten können.

## Consequences

Die bestehenden Daten müssen geprüft und ggf. zu UTC migriert werden. Die Verantwortung des
richtigen Zeitstempels liegt bei der Anwendung. Das neue Datumsformat muss in der
Benutzeroberfläche oder Berichten beachtet und ggf. in lokale Zeit umgewandelt werden.

Gehen wir etwas genauer auf die einzelnen Bestandteile ein:

Dateiname: Die Datei sollte immer mit der Nummer anfangen und den Titel beinhalten. Viele ADR-Programme machen das standardmäßig so. Die Nummer erlaubt eine eindeutige Referenzierung, falls notwendig.
Titel: Im Titel steht sowohl die Nummer des ADR als auch die Entscheidung. Der Titel sollte möglichst eindeutig und verständlich sein.
Date: Das Datum, an welchem der ADR beschlossen oder aktiv wurde.
Status: Wie ist der Zustand des ADRs? Mögliche Status sind Accepted, Superseded oder Deprecated. Hierdurch kann jemand schnell erkennen wie der Zustand ist. Manche Tools erlauben die Erstellung eines Inhaltsverzeichnisses, wo der Status angezeigt wird.; Hier ein kleiner Tipp: Wenn ein ADR den Status wechselt, dann bietet es sich an den Grund ebenfalls kurz zu dokumentieren oder im Falle eines Superseded (ersetzt durch) auf das neue ADR zu verlinken.
Context: Hier wird das Umfeld beschrieben. Wo bewege ich mich? Gibt es Abhängigkeiten? Gibt es technische oder organisatorische Vorgaben, die umgesetzt werden müssen? Was hat diesen ADR beeinflusst?
Decision: Da der Titel recht kurz ist, wird hier die Entscheidung detaillierter festgehalten. Was führte zu der Entscheidung? Wurden Alternativen beleuchtet?
Consequences: Jetzt, wo die Entscheidung getroffen ist, was ergeben sich für Konsequenzen? Hier können sowohl gute als auch schlechte Punkte genannt werden. Gibt es Risiken? Sind bestimmte Funktionen blockiert oder nur noch mit hohem Aufwand möglich? Muss ich Mitarbeiter schulen oder einweisen?

Allgemeine Hinweise / Zusammenfassung

Ein ADR ist kurz und prägnant.
Ein ADR hat eine eindeutige Nummer.
Ein ADR verwendet vollständige Sätze.
Ein ADR ist im Aktiv geschrieben.
Ein ADR ist einheitlich aufgebaut.
Die Struktur eines ADR kann individuell angepasst werden.
Der Titel/Dateiname ist sprechend. Das ermöglicht schnelleres Auffinden. Wie hier: “Zeitstempel werden im UTC Format in der Datenbank gespeichert” statt “Datumsformat in der Datenbank”.
Die Inhalte können auch als Liste erfasst werden. Achtet hier darauf, dass es trotzdem vollständige Sätze sind. Nach 1-2 Jahren könnt ihr mit Stichpunkten (wahrscheinlich) nichts mehr anfangen.
Es gibt Programme, mit denen sich ADRs verwalten und erstellen lassen. Diese nehmen euch viel Arbeit ab.

Fazit

Das Ziel eines ADR ist es, schnell einen Überblick über Entscheidungen zu geben und Entscheidungen nachvollziehbar zu dokumentieren. Aufgrund der schlanken Struktur ist die Hürde sehr niedrig und es kann schnell im Projekt eingesetzt werden. Habt ihr bereits mit ADRs Erfahrung gesammelt oder es in euren Projekten im Einsatz? Was ist euch bei ADRs wichtig?

Bildnachweis: Pixabay

Weitere Quellen: