Gut dokumentiert: Architecture Decision Records

Inhaltsverzeichnis

Architekturdokumentation soll anderen Menschen beim Verständnis der entwickelten Software helfen. Welche Methode und wie viel Aufwand für die Dokumentation richtig ist, müssen Teams individuell entscheiden. Ein schlanker Ansatz, der sich leicht in die tägliche Arbeit integrieren lässt, sind Architecture Decision Records (ADR).

Fast jeder kennt Momente, bei denen sich Fragen nach dem Warum stellen: Warum hat jemand etwas auf die eine Weise und nicht anders erledigt? Warum hat ein Team eine bestimmte Technik gewählt? Warum hat niemand die Konsequenzen gesehen, die daraus entstehen konnten? Auslöser für die Fragen können einzelne, kurze Methoden oder die Gesamtarchitektur sein. Dahinter steht wiederum die Frage, ob das Team die Entscheidung sorgfältig getroffen und überdacht hat.

Letzteres ist wahrscheinlich, aber häufig lässt sich für andere nicht nachvollziehen, welcher Gedanke zu der vorliegenden Entscheidung geführt hat und welches Ziel dahintersteht. Die Anwender kennen nur das Ergebnis und die Auswirkungen, aber nicht den Weg, der zu der Entscheidung geführt hat.

Keine falschen Entscheidungen

Wer eine Entscheidung trifft, verfolgt üblicherweise ein Ziel. Dabei gilt es, zahlreiche Aspekte zu berücksichtigen und viele Informationen in die Entscheidungsfindung einzubeziehen. Menschen müssen seit Urzeiten ständig Entscheidungen treffen und können das üblicherweise gut, wenn sie mit der gleichen oder einer ähnlichen Situation vertraut sind.

Sie können auf Erfahrung zurückgreifen, wenn sie die Ausgangssituation, das angestrebte Ziel und die sich daraus ergebenden Konsequenzen kennen. Je weniger über das zu lösende Problem, mögliche Lösungsansätze und deren Konsequenzen bekannt ist, desto schwieriger ist die Entscheidung.

Wissen und Unwissen

Zur Klassifikation von Wissen existieren zahlreiche Modelle. Eines davon setzt auf eine 2x2-Matrix aus "Known" und "Unkown". Demnach gibt es auf der einen Seite die Known Knowns, also Wissen, das jemand bewusst wahrnimmt. Auf der anderen Seit gibt es die Unknown Unknowns: Wissen, das jemand nicht nur nicht hat, sondern auch nicht weiß, dass es fehlt. Ergänzt wird die Matrix durch die Known-Unknowns und die Unkown-Knowns.

Ersteres stellt Wissen dar, über dessen Fehlen sich jemand bewusst ist und sich aneignen oder das Fehlen als Risiko einkalkulieren kann. Letzteres ist Wissen, dass zum Einsatz kommt, ohne dass sich derjenige darüber im Klaren ist, dass er es hat. Der Einteilung in diese Matrix hat der ehemalige US-amerikanische Verteidigungsminister Donald Rumsfeld auf einer Pressekonferenz 2002 im Vorfeld des Dritten Golfkrieges zu Bekanntheit verholfen.

Zu den objektiven kommen noch die subjektiven Einflussfaktoren, die mit der individuell handelnden Person zusammenhängen. Unter anderem sind Werte und Moral ein subjektiver Einflussfaktor. Menschen neigen dazu, ihre subjektiven Faktoren als objektiv darzustellen und wahrzunehmen. Demnach kann es keine objektiv richtigen Entscheidungen geben.

Damit ist jede Entscheidung aus Sicht desjenigen, der sie trifft, zunächst subjektiv richtig. Sie erfüllt ihren Zweck zu dem Zeitpunkt und für die Person in der Situation mit dem Wissen sowie der jeweiligen Erfahrung.

Das mag beschönigend klingen, hilft aber dabei, die Situation nüchterner zu betrachten. Per se gibt es somit keine falschen Entscheidungen. Zum Zeitpunkt der Entscheidung lässt sich oft nicht abschätzen, welche Folgen sie haben wird. Und es ist nicht auszuschließen, dass eine vielleicht anfangs als falsch beurteilte Entscheidung sich später als die bessere Entscheidung in Hinblick auf die Konsequenzen erweist.

Nachvollziehbare Architektur

Entscheidungen festzuhalten, sie zu dokumentieren ist ein wichtiger Bestandteil der Arbeit an einer Softwarearchitektur. Nur auf die Weise können andere später die Entwicklung eines Systems und die Leitgedanken nachvollziehen. Bei weiteren Entscheidungen lässt sich qualifiziert überlegen, ob das Team die Entscheidungen beibehalten oder etwas ändern soll. Diskussionen, ob beispielsweise ein Framework X das Framework Y ersetzen soll, lassen sich anders führen, wenn die Beteiligten sich auf vorherige Entscheidungen beziehen können, zu denen die jeweiligen Entscheider Stellung beziehen müssen.

Zu einer gut dokumentierten Entscheidung gehört die Situation, in der sie getroffen wurde, aber auch die verfolgten Ziele. Das gilt unabhängig davon, ob Teams für Softwareprojekte anfangs viel Zeit in das Erarbeiten einer Softwarearchitektur investiert haben oder die Softwarearchitektur im Lauf des Projekts erstellen. Bei beiden Ansätzen stehen immer wieder Entscheidungen an. Grundsätzlich gilt: Je länger ein Projekt läuft, desto mehr Entscheidungen sind im Lauf der Zeit im Vergleich zum Start gefallen. Dokumentationen, die nur zu Beginn entstehen, sind daher veraltet und teilweise nutzlos, da sie nicht dem aktuellen System entsprechen und mehr Verwirrung stiften als Nutzen schaffen.

Teams müssen beziehungsweise können nicht jede Entscheidung dokumentieren. Auf die Frage, welche es zu dokumentieren gilt, gibt es keine pauschale Antwort. Ob für ein Java-System Apache Commons oder Google Guava zum Einsatz kommt, muss nur dann in die Dokumentation einfließen, wenn es eine explizite Entscheidung gegen eine der beiden Bibliotheken gibt. Ebenso müssen Teams nicht unbedingt dokumentieren, ob sie anfangs PostgreSQL oder MariaDB einsetzen, eine Migration von einer der beiden zu Cassandra hingegen durchaus.

Gute Anzeichen für die Notwendigkeit der Dokumentation ist, wenn eine Entscheidung von bestehenden Best Practices oder eigenen Standards abweicht oder ihr lange Diskussionen vorausgegangen sind.

Angstfrei dokumentieren

In der idealen Welt ist jede Entscheidung durch das Abwägen der bekannten Fakten, des verfügbaren Wissens und der Werte bestimmt. In der Praxis fallen jedoch selten einheitlich als optimal betrachtet Entscheidungen, sondern oft sind Kompromisse das Beste, was erreichbar ist. Äußere Rahmenbedingungen wie Zeit, Geld oder Konflikte im Team haben ebenfalls Einfluss auf Entscheidungen.

Derartige Gründe offen anzusprechen und beispielsweise einzuräumen, dass eine Idee zu wenig Unterstützung gefunden hat, erfordert Mut. Dennoch ist es wichtig, solche Fakten festzuhalten.