Architecture Decision Records.

Architecture Decision Records

TL;DR

Architecture Decision Records (ADRs) sind ein leichtgewichtiges Werkzeug zur Dokumentation Ihrer Entscheidungen. Sie wurden von Michael Nygard im Jahr 2011 erfunden. ADRs helfen Ihnen, Ihrem Team und einem potenziellen Nachfolger zu verstehen, warum etwas auf eine bestimmte Weise gebaut wurde.

ADRs sind ein großartiges Werkzeug, um über potenzielle Vor- und Nachteile nachzudenken. Sie helfen, gemeinsam mit Ihrem Team und Stakeholdern eine Vorgehensweise zu entscheiden.

Das Problem

Wenn Sie Ingenieur sind, dann kennen Sie das Gefühl, wenn Sie zu einem älteren Softwaresystem kommen: “Wow! Das sieht wirklich seltsam aus - warum wurde das so gemacht???”. Meine erste Reaktion ist immer sehr kindisch und ich nehme an, dass die Ersteller inkompetent waren. Aber das ist natürlich nie wahr. Ich bin einfach nur dumm.

Software sieht so aus, wie sie aussieht, aus sehr guten Gründen. Business, Technologie und Menschen haben alle einen erheblichen Einfluss.

Wenn wir diese Gründe nicht kennen, passieren mindestens zwei schlechte Dinge:

  • Wir werden Schwierigkeiten haben zu verstehen, warum ein System auf eine bestimmte Weise gebaut wurde
  • Wir werden die gleichen Fehler wiederholen

Autsch.

Eine Lösung

Architecture Decision Records zur Rettung!

ADRs sind ein großartiges und leichtgewichtiges Werkzeug zur Dokumentation Ihrer Entscheidungen. Das macht es sehr einfach für Sie und Ihre Nachfolger, über Entscheidungen zu lesen. Es stellt sicher, dass Sie nicht die gleichen Fehler wiederholen (“Ah - jetzt weiß ich, warum sie es so gemacht haben - verdammt - ich muss die Änderungen der letzten zwei Wochen rückgängig machen”).

ADRs unterstützen Sie in zwei Schlüsselbereichen.

  1. Eine ordentliche Architekturentscheidung braucht schriftliche Dokumentation und ein ordentliches Zusammenfassen von Vor- und Nachteilen. Das erleichtert auch die Diskussion mit Ihrem Team und Stakeholdern. ADRs sind genau das: Ein nettes Writeup von Architekturentscheidungen, bereit zur Diskussion.
  2. Sie ermöglichen eine Zeitreise. Sie können nachlesen, warum etwas auf eine bestimmte Weise entschieden wurde. Das hilft nicht nur den nächsten Generationen von Ingenieuren, sondern auch Ihnen, Fehler nicht zu wiederholen und aus der Vergangenheit zu lernen.

Wie ADRs aussehen

Architecture Decision Records wurden von Michael Nygard im Jahr 2011 erfunden. Sie sind - absichtlich - sehr einfach und haben einen Titel und 4 Abschnitte.

  • Context: Hintergrund zu dieser Entscheidung. Warum wir darüber sprechen. Vor- und Nachteile.
  • Decision: Was wurde entschieden und warum.
  • Status: Ein Status wie “accepted, rejected, proposed…”
  • Consequences: Was ist das Ergebnis. Wird etwas einfacher? Welche Nachteile akzeptieren wir?

Ein Beispiel

Hier ist ein Beispiel eines Architecture Decision Record:

# Context
Our current database system does not allow extended join operations
needed for our upcoming business use cases.

## Options

### We can keep our database system and do the joins manually in our applications
#### Pros
- No new database system
- Everything stays the way it is

#### Cons
- A lot more logic and complexity in our applications
- Performance can be critical

### We could move to a different database system like FooDB that supports these joins
#### Pros
- Logic in code stays simple. Joins are also simple to express in SQL.
- Database system has many more advantages that could be beneficial in the future

#### Cons
- All applications on our side have to move to new database driver
- There might be incompatibilities that we only find out when running the apps
- We understand our old database system perfectly fine (Ops, developers)

# Decision
We'll move to FooDB. It supports all join types we need and is in active
development. Moving the data will incur a minimal downtime. The database system
can also run on AWS which means we don't have to do the maintenance and operation
any more. We'll gradually roll out the changes to user cohorts step by step so
that we can find bugs and minimize the impact.

# Status
ACCEPTED

# Consequences
- We have to use different database drivers to access the database
- A workgroup been set up to move the data
- Ops team will support the move and take over operation on AWS

Zusätzliches Tooling

Es gibt zusätzliches Tooling unter https://github.com/npryce/adr-tools. Meiner Meinung nach brauchen Sie es nicht wirklich. Jedes Wiki oder Git-Repo mit Markdown-Dateien wird perfekt sein. Fangen Sie einfach an. Verwenden Sie die Struktur mit vier Abschnitten (Context, Decision, Status, Consequences) und ordnen Sie sie.

Fazit

Architecture Decision Records sind ein großartiges Werkzeug, um strukturiert über Architektur nachzudenken. Vermeiden Sie es auf eigene Gefahr!

Mehr

Imprint | Privacy Policy