Software Architektur dokumentieren

Im Laufe meiner Karriere als Softwareentwickler bin ich häufig auf Legacy-Systeme gestoßen, die über Jahre hinweg organisch gewachsen sind. Das ursprüngliche Entwicklungsteam ist oft längst nicht mehr da, und die hinterlassene Dokumentation ist entweder veraltet oder nicht existent. Dieser Mangel an Kontext macht es neuen Teams unglaublich schwer, die bestehende Software zu verstehen und effektiv zu warten. In solchen Situationen greifen Entwickler oft zu einem von zwei gleichermaßen problematischen Ansätzen: Entweder akzeptieren sie frühere Architekturentscheidungen blindlings oder ändern sie ohne ausreichendes Verständnis.

In solchen Fällen beginnen Teams in der Regel damit, technische Diagramme zu erstellen, um die aktuelle Softwarearchitektur festzuhalten. Diese helfen zwar, den gegenwärtigen Zustand des Systems zu verstehen, beantworten jedoch nicht die entscheidende Frage: Warum hat das frühere Team das System auf diese Weise entworfen?

Genau hier kommen Architecture Decision Records (kurz ADRS), ins Spiel. Sie liefern eine Dokumentation, die nicht nur erklärt, was gebaut wurde, sondern auch, warum es so gebaut wurde.

Was sind Architecture Decision Records?

Architecture Decision Records (ADRs) sind eine systematische Methode, um die kritischen Designentscheidungen zu dokumentieren, die von Softwarearchitekten und Entwicklungsteams während des Softwaredesign- und Implementierungsprozesses getroffen werden. ADRs liefern entscheidende Kontextinformationen, indem sie die Gründe hinter den Architekturentscheidungen erklären. Durch die Erfassung des „Was“ und des „Warum“ helfen ADRs den Beteiligten, die Überlegungen, potenziellen Auswirkungen, Kompromisse und strategischen Vorteile von Architekturentscheidungen zu verstehen. Das verbessert die Kommunikation und die langfristige Wartbarkeit des Systems.

Ein Architecture Decision Record (ADR) enthält typischerweise fünf zentrale Komponenten: einen Titel, den Status, den Kontext, die Entscheidung und die Konsequenzen. Obwohl diese Standard sind, können Projekte zusätzliche Felder für eine umfassendere Dokumentation hinzufügen.

Titel Wähle einen prägnanten, nummerierten Titel, der die Essenz der Architekturentscheidung präzise einfängt, um eine schnelle Identifikation und Referenzierung zu ermöglichen.

Status Markiere den aktuellen Status der Entscheidung klar: vorgeschlagen, akzeptiert, abgelehnt oder ersetzt. Für abgelehnte oder ersetzte ADRs sollte ein Verweis auf das alternative ADR enthalten sein.

Kontext Umreiße die spezifischen Umstände, Einschränkungen und die technische Landschaft, die diese Architekturentscheidung erforderlich machten.

Entscheidung Formuliere die Architekturentscheidung klar und unmissverständlich. Verwende deutliche, bejahende Sprache, die keinen Raum für Fehlinterpretationen der gewählten Vorgehensweise lässt.

Konsequenzen Dokumentiere die potenziellen kurz- und langfristigen Auswirkungen der Entscheidung. Analysiere kritisch und präsentiere sowohl die Vorteile als auch die potenziellen Herausforderungen dieser Architekturentscheidung.

Zusätzliche Felder Passe deine ADRs mit zusätzlichen Feldern an, die auf dein Projekt- und Teampräferenzen abgestimmt sind. Zum Beispiel kannst du einen Abschnitt für Alternativen hinzufügen, um alternative, aber nicht gewählte Lösungen zu präsentieren.

Wie ein ADR aussehen könnte ?

Betrachten wir ein Beispiel aus der Praxis eines typischen Softwareprojekts, um zu veranschaulichen, wie ein ADR funktioniert. Angenommen, du arbeitest an einer wachsenden Anwendung, die ein API-Gateway benötigt, um die Kommunikation zwischen Client und Service zu verwalten. Ohne ein zentrales Gateway sind die Frontend- und Backend-Services locker gekoppelt, was zu inkonsistenter Weiterleitung, Authentifizierung und Sicherheitsrichtlinien führt. Die finale Architektur könnte etwa so aussehen:

Um die Entscheidung zur Nutzung von NGINX und dessen Konfiguration gemäß dem Diagramm zu dokumentieren, würde folgendes ADR erstellt:

### ADR-001 Nutzung eines NGINX-API-Gateways

**Status**

akzeptiert

**Kontext**

Unsere Anwendung benötigt ein API-Gateway, um die Kommunikation zwischen Clients
und Services zu optimieren und einen einheitlichen Zugriff sowie eine konsistente
Weiterleitung zu gewährleisten. Dieses Gateway wird die Weiterleitung
zentralisieren, einheitliche Sicherheitsrichtlinien durchsetzen und die
Kommunikation zwischen Frontend und Backend vereinfachen.

**Entscheidung**

Wir verwenden NGINX als API-Gateway mit folgender Konfiguration:
- SPA-Frontend-Bereitstellung: Die SPA-Frontend-Anwendung wird unter dem Endpoint `/` ausgeliefert.
- Backend-Weiterleitung: Alle Backend-Services sind über den Endpoint `/api/**` zugänglich.
- SSO-Integration: Der SSO-Dienst wird unter dem Endpoint `/auth` bereitgestellt.

**Konsequenzen**

- Einheitlicher Zugriff: Alle Client-Anfragen werden über das API-Gateway geleitet.
- Verbesserte Sicherheit: Direkter Zugriff auf Backend-Services über deren interne Domains wird eliminiert, wodurch die Angriffsfläche reduziert wird.

NGINX wurde aufgrund folgender Gründe ausgewählt:

- Bewährte Fähigkeit, hohe Concurrency und Traffic zu bewältigen
- Flexible Konfigurationsoptionen für Routing und Load-Balancing
- Kompatibilität mit modernen Authentifizierungs- und API-Sicherheitsmustern

Mit dem ADR-001 Nutzung eines NGINX-API-Gateways dokumentierst du erfolgreich die Architekturentscheidung. Dies hilft allen Projektbeteiligten, diesen speziellen Teil der Architektur besser zu verstehen.

Wie mit ADRs anfangen?

Der beste Zeitpunkt, um mit der Dokumentation von Architekturentscheidungen zu beginnen, ist jetzt. Erstelle zunächst eine wiederverwendbare ADR-Vorlage, die dein Team für zukünftige Entscheidungen leicht duplizieren kann. Für bestehende Projekte konzentriere dich zunächst auf die Dokumentation neuer Architekturentscheidungen, anstatt jede vergangene Entscheidung zu erfassen, was überwältigend sein kann. Wenn du bei deiner aktuellen Aufgaben auf frühere, nicht dokumentierte Entscheidungen stlößt, nehmen dir einen Moment Zeit, um diese zu dokumentieren.

Das Hauptziel ist es, Zugänglichkeit und Sichtbarkeit für alle Projektbeteiligten zu gewährleisten. Wählen einen Speicherort für die ADRs, die zum Workflow deines Teams und zu den Dokumentationsstandards der Organisation passen.

Für Softwareprojekte empfehle ich folgende Speicherort:

• In Open-Source-Projekten, die Git-Repositories verwenden, speicherne ADRs als Markdown-Dateien neben Code und Dokumentation.
• Für Teams, die Wiki-Plattformen wie Confluence verwenden, erstelle einen speziellen ADR-Space, der leicht durchsuchbar ist.
• Enterprise-Teams könnten spezialisierte Dokumentationstools oder versionierte Repositories nutzen, die sich nahtlos in bestehende Entwicklungs-Workflows integrieren lassen.

Warum die Erstellung von ADRs wichtig ist?

Das Schreiben von Architektur-Entscheidungsprotokollen (ADRs) ist aus mehreren Gründen hilfreich:

• Alignment: ADRs stellen sicher, dass alle Teammitglieder ein klares, gemeinsames Verständnis der wichtigen Architekturentscheidungen haben. Sie bieten eine zentrale Informationsquelle, die die technische Vision zwischen verschiedenen Teams, Abteilungen und zukünftigen Mitwirkenden, die nicht an der ursprünglichen Entscheidungsfindung beteiligt waren, ausrichtet.
• Wissensaustausch: ADRs dienen als lebendige Dokumentation, die nicht nur festhält, welche Entscheidungen getroffen wurden, sondern auch die Gründe dafür. Dieser Wissensaustausch ist entscheidend für die Einarbeitung neuer Teammitglieder und verhindert den Verlust von Wissen bei Personalwechseln.
• Langfristige Wartbarkeit: Durch die Dokumentation von Architekturentscheidungen schaffen Teams ein historisches Protokoll, das künftigen Entwicklern hilft zu verstehen, warum bestimmte technische Ansätze gewählt wurden. Dieser Kontext ist bei der Wartung, Refactorings oder Skalierung von Softwaresystemen von unschätzbarem Wert.
• Teamwork: Jedes Teammitglied kann Vorschläge zur Verbesserung der Softwarearchitektur einbringen. ADRs schaffen eine transparente, kollaborative Umgebung, in der technische Entscheidungen nicht isoliert, sondern durch kollektiven Input, Überprüfung und Konsens getroffen werden. Dieser Ansatz fördert eine Kultur der kontinuierlichen Verbesserung und gemeinsamen Verantwortung für die technische Strategie.

Fazit

Architektur-Entscheidungsprotokolle (ADRs) sind ein mächtiges Werkzeug, um Architekturentscheidungen in der Softwareentwicklung zu dokumentieren und zu kommunizieren. Sie liefern Klarheit über das „Warum“ hinter Architekturentscheidungen, fördern die Ausrichtung im Team, erleichtern den Wissensaustausch und verbessern die Wartbarkeit.

This post was originally published in English on Medium.com .