Softwarearchitektur Artikelreihen

Architectural Decision Records - Theorie und Praxis

In diesem Tool Talk handelt es sich diesmal um ADR (Architectural Decision Records). Dabei wird nicht nur das Konzept dahinter vorgestellt, sondern auch ein paar Tipps und Tricks aus der Praxis.

Thomas Ronzon

Projektleiter und Senior Softwareentwickler

28.09.2023
Lesezeit: 12 Minuten
107 Views

Was sind ADR?

Die Idee, seine Architektur und besonders die Entscheidungen, die zu dieser Architektur geführt haben, mit ADR zu dokumentieren, ist nicht neu. Bereits 2011 beschrieb Michael Nygard [NYG] die ADR (Architectural Decision Records). Diese sollten knapp gehalten werden und die Entscheidung beschreiben, nicht den langen Weg dorthin, den im Zweifelsfall eh keiner liest.

Zum Schreiben eines ADR benötigst du nichts weiter als einen Editor, der einfachen Text erzeugt. Du siehst – die Hürden sind so gering wie möglich gehalten. Genaueres zum Schreiben eines ADR findet sich hier [ADRH]. Es gibt aber auch einen schönen Podcast, in dem Michael Stal und Eberhard Wolff über die Vor- und Nachteile von ADR philosophieren [ADRP].

So oder so solltest du – bevor du dir eine Meinung bildest – einmal 2 bis 3 ADR selbst verfassen und von einem anderen Mitglied im Team lesen lassen. Dadurch, dass du versuchen solltest, die ADR so kurz und präzise wie möglich zu halten, kannst du beim Schreiben nämlich auch erkennen, wenn du verschiedene Dinge, die eigentlich nicht zusammengehören, zusammenfasst. Das Problem ist dann, dass deine Gedankengänge für spätere Leser der ADR nur schwer verständlich sind.

Tipp: Es lohnt sich meiner Meinung nach, bei einem bestehenden System nicht sehr viel Zeit damit zu „verschwenden“, alle Dinge nachzudokumentieren. Nutze die Zeit lieber, um ein paar grundlegende Entscheidungen zu dokumentieren, die neuen Mitgliedern im Team vielleicht nicht so verständlich sind. Später kannst du dann weitere Entscheidungen hinzufügen.

ADR-Tools – wenn es etwas komfortabler sein soll

Wie bereits oben beschrieben handelt es sich bei den ADR um einfache Textdateien. Um aber sicherzustellen, dass diese immer gleich aufgebaut sind, beziehungsweise um diese etwas einfacher erstellen zu können, gibt es die ADR-Tools [ADRT]. Das Repository ist zwar schon relativ lange nicht mehr aktualisiert worden, aber die Shell-Skripte erfüllen trotzdem ihren Zweck. Besonders schön finde ich auch, dass diese Skripte nicht nur unter Linux und Mac OS funktionieren, sondern genauso in der git-bash, die ja ab Windows 10 mitgeliefert wird.

Installation

Für die Installation genügt es, das Repository zu clonen und dann das src-Verzeichnis zum Pfad hinzuzufügen, etwa mittels:

export PATH=~//adr-tools-master/src:$PATH

Ob man unter Windows wirklich (wie in der beigefügten Anleitung beschrieben) kein eigenes Verzeichnis verwenden möchte, sondern die Skripte in das Verzeichnis C:\Program Files\Git\usr\bin kopiert, sei jedem selbst überlassen.

Die ersten Schritte

Um zu prüfen, ob die „Installation“ funktioniert hat, genügt einfaches:

adr help

usage: adr help COMMAND [ARG] ...
COMMAND is one of:
config
generate
help
init
link
list
new
upgrade-repository
Run 'adr help COMMAND' for help on a specific command.

Das Anlegen eines Repositories

Als Erstes muss einmalig ein Repository für die ADR angelegt werden:

adr init projekte/adr-js

Dabei wird nicht nur ein entsprechendes Verzeichnis angelegt, sondern sofort eine initiale Datei mit einem ADR (s. Abb. 1).

Abb. 1: Ein initialer ADR

Der erste eigene ADR

Ein eigener ADR wird genauso einfach angelegt:

adr new <ADR-Name>

zum Beispiel:

adr new Mein erster ADR

Schauen wir ihn uns einmal in Abbildung 2 an. Sieht ähnlich aus, oder?

Schaut man aber genauer hin, so haben die ADR-Tools nicht nur die Struktur generiert, sondern sowohl innerhalb des Namens als auch beim Dateinamen die IDs richtig gepflegt. Von nun an kann er in jedem Editor bearbeitet werden.

Bis hierher ist das Ganze relativ unspannend.

Abb. 2: Der erste eigene ADR

Ändern eines bestehenden ADR

Möchte man einen ADR anpassen, weil sich die Entscheidung geändert hat, so kann man dies natürlich mit einem Editor erledigen. Problem dabei ist, dass so zum einen die Historie verloren gehen würde und es zum anderen lästig ist, zum Beispiel den Status zu pflegen. Leichter geht es mit:

adr new -s 2 Mein neuer ADR

Durch die Option -s wird nämlich angezeigt, dass der ADR obsolet ist und durch einen weiteren ersetzt wurde. Dies wird dabei direkt im ursprünglichen ADR vermerkt, in dem der Status umgesetzt und gleichzeitig ein Vermerk zu dem neuen ADR generiert wird (s. Abb. 3).

Abb. 3: Der geänderte ADR

Aber auch im neuen ADR wird der Verweis zum Ursprungs-ADR gespeichert, wie man in Abbildung 4 sehen kann. Soll nicht der ganze ADR, sondern nur einzelne Teile geändert werden, so hilft die Option -l, wie man in Abbildung 5 sehen kann. Hier das vollständige Kommando:

adr new -l '3:Dependency:Influences' Neue JavaSpektrum am Kiosk

Abb. 4: Der neue ADR mit Verweis auf den Ursprung

Abb. 5: Auch einzelne Abschnitte können geändert werden

Eigene Templates

Das mitgelieferte Template ist bewusst einfach gehalten. Sollte dir das Aussehen des ADR nicht gefallen, so findest du die Dokumentenvorlage unter adr-tools-master/src/template.md. Diese ist auch kommentiert, sodass du dieses für deine Projekte anpassen kannst.

Der Aufbau für eigene Skripte

Sicher sind die Skripte nicht spektakulär – sie sind eigentlich genau so einfach wie das Prinzip der ADR selbst. Dies bedeutet im Umkehrschluss aber auch, dass du diese ganz einfach an deine Projektbedürfnisse anpassen kannst. Dreh- und Angelpunkt ist das Skript adr im src-Verzeichnis. Dieses dient quasi als „Wegweiser“ und ruft dann die anderen Skripte (Kommandos) auf. Möchtest du also Aktionen bei allen Kommandos ausführen, so bist du hier richtig.

Alle Kommandos sind dann unter dem Namenskürzel adr-com-mand, zum Beispiel adr-new, zu finden. Ein neues Kommando kann so einfach durch Hinzufügen eines Skripts mit den oben beschriebenen Namenskonventionen erstellt werden.

Tipp: Nimm am besten eins der bestehenden Kommandos als Basis. Das folgende adr-list ist eine gute Basis für eigene Kommandos:

#!/bin/bash
set -e
eval "$($(dirname $0)/adr-config)"

## usage: adr list
##
## Lists the architecture decision records

adr_dir=$("$adr_bin_dir/_adr_dir")

if [ -d $adr_dir ]
then
find $adr_dir | grep -E "^$adr_dir/[0-9]+-[^/]*\\.md" | sort
else
echo "The $adr_dir directory does not exist"
exit 1
fi

Tipps zur täglichen Arbeit

Sicher – das Erstellen von ADR ist ziemlich einfach, aber was soll das Ganze? Bereits am Anfang habe ich ja erwähnt, dass ADR dazu gedacht sind, Architekturentscheidungen nicht nur zu dokumentieren, sondern auch um zu verstehen, wie es zu der Entscheidung gekommen ist. In einem lebenden Projekt kann es deshalb schnell über 100 ADR geben. Den richtigen zu finden, ist dann gar nicht so einfach. Eine einfache Suche innerhalb der ADR ist deshalb ziemlich sinnvoll. Bereits in anderen Kolumnen habe ich schon gezeigt, wie man hier einfach Apache Lucene [AL] verwenden kann. Trotzdem möchte ich hier noch einmal einen kurzen Ausblick zur Verwaltung von ADR mit Lucene geben.

Wie wir gesehen haben, speichern die ADR-Tools alle ADR in dem Verzeichnis des Repositories. Um diese zu durchsuchen, genügt es, dieses Verzeichnis zu indizieren. Am einfachsten geht dies, wenn man das Programm IndexFiles.java von den Lucene-Demos als Basis nimmt. Dies wird im Sourcecode von Lucene mitgeliefert und kann hier [LS] heruntergeladen werden. Im Verzeichnis lucene/demo/src/java/org/apache/lucene/demo findet man etwas versteckt dies Programm.

Anlegen eines Index und Hinzufügen der ADR

Um unsere ADR durchsuchbar zu machen, müssen wir zunächst einen Lucene-Index anlegen. Dies geschieht hier unter dem per Parameter mitgegebenen Indexpfad. Nun können die Dateien, also unsere ADR, dem Index hinzugefügt werden. Dabei wird auch das Verzeichnis mit den Dokumenten per Parameter angegeben.

Soll das Programm aber nicht nur zum Spielen, sondern produktiv eingesetzt werden, so solltest du die Speicherzuweisung der JVM einmal ansehen, wie auch im Sourcecode vermerkt ist:

// Optional: for better indexing performance, if youif (reader.numDocs() > 100 && vectorDictSize < 1_000_000 &&
System.getProperty("smoketester") == null) {
throw new RuntimeException(
"Are you (ab)using the toy vector dictionary? See the package javadocs to
understand why you got this exception."
);}

Suchen im Index

Das Suchen im Index ist genauso einfach. Auch hier gibt es ein mitgeliefertes Beispiel. Das Programm SearchFiles.java findest du auch unter lucene/demo/src/java/org/apache/lucene/demo.

Aber auch hier sollte man sich bewusst sein, dass es sich um eine Demo handelt. So wird im Programm die Ausgabe der Ergebnisse limitiert – in unserem Anwendungsfall wollen wir aber alle ADR sehen. Verantwortlich hierfür ist dieser Teil, der nach eigenen Wünschen modifiziert werden sollte:

// Collect enough docs to show 5 pages
TopDocs results = searcher.search(query, 5 * hitsPerPage);
ScoreDoc[] hits = results.scoreDocs;

int numTotalHits = Math.toIntExact(results.totalHits.value);
System.out.println(numTotalHits + " total matching documents");

Aber auch für andere Wünsche gilt bei diesen beiden Demos das Gleiche wie für die ADR-Tools: Die Programme sind so einfach aufgebaut, dass du sie leicht an deine Bedürfnisse anpassen kannst.

Fazit

ADR sind schnell erstellt und helfen – bei deren entsprechender Organisation – auch später noch zu wissen, wie manche Teile aufgebaut sind. Weitere Informationen findest du hier [ADRA]. Spätestens aber, wenn man mehr als 10 ADR hat, sollte man sich auch Gedanken über die Verwaltung und den Zugriff machen.