Hand hoch, wer es kennt: da kommst du in ein bestehendes Softwareprojekt und wünschst dir, irgendjemand™ hätte sich die Zeit genommen, wichtige Entscheidungen irgendwo zu dokumentieren.
Warum, zum Beispiel, werden zur Service-Kommunikation HTTP Requests eingesetzt? Warum kein Message Bus? Was war der Grund für diese Entscheidung? Hatten die Entscheider auf dem Schirm, dass es auch andere Kommunikationsmöglichkeiten gibt? Wurden die beachtet? Warum verwenden wir Sprache X mit Framework Y?
ADR – Architectural Decision Records
Zum Glück gibt es jetzt (okay, bereits seit 2018 …) ein Format, mit dem sich strukturiert nachvollziehen lässt, warum einst eine Entscheidung in einem Softwareprojekt gefallen ist. Auf Wunsch sogar versioniert! Die Tools dazu bringst du als Entwickler:in sogar mit.
Bei Dokumentation zu Software muss ich immer an sehr lange und umständlich formulierte Textkataloge denken. Architectural Decision Records (ADR) beschränken sich dagegen auf das Nötigste. Hier ein Beispiel mit einem sehr kurzen Format namens Markdown Any Decision Records (MADR):
# 001 - Use Plain JUnit5 for advanced test assertions ## Context and Problem Statement How to write readable test assertions? How to write readable test assertions for advanced tests? ## Considered Options * Plain JUnit5 * Hamcrest * AssertJ ## Decision Outcome Chosen option: "Plain JUnit5", because it is a standard framework and the features of the other frameworks do not outweigh the drawbrack of adding a new dependency.
Quelle: https://github.com/adr/madr
Die Dokumentation
Hier wird kurz und knackig aufgelistet, was es Wissenswertes zu dem Thema gibt. Und das im simplen Markdown-Format (kann man aber auch in Plaintext schreiben oder in einem Word-Dokument festhalten).
- In Zeile 1 gibt die Überschrift die Entscheidung wieder; am besten wird auch die Datei nach der Überschrift benannt, dann ist von außen gut erkennbar, worum es geht. Und weil wir gerade davon sprechen: für jede Entscheidung wird eine eigene Datei angelegt.
- Nach der Überschrift (Zeile 3) folgt kurz eine Schilderung der Problematik. Was soll erreicht werden? Was ist das konkrete Problem, welches mit dieser Entscheidung gelöst werden soll?
- Anschließend (Zeile 8) wird in Stichpunkten aufgelistet, welche Optionen in Betracht gezogen wurden. Gibt es mehrere Testing-Frameworks? Mehrere Sprachen, die geeignet wären? Mehrere Wege, die zum Ziel führen?
- Und am Schluss (Zeile 14) muss die Entscheidung mitgeteilt werden. Welche Option wurde gewählt und warum?
So ist auch für künftige Entwicklergenerationen (und andere Projektbeteiligte) jederzeit nachvollziehbar, warum eine bestimmte Entscheidung getroffen wurde.
Hast du deine Entscheidung niedergeschrieben, ist es noch eine gute Idee, die Datei in die Versionsverwaltung mit einzuhängen. Sie könnte in einem eigenen Ordner für Dokumentation oder in einem eigenen Repository abgelegt werden. So geht auch keine Änderung verloren.
… in ausführlich
Hier habe ich für dich auch noch eine ausführlichere Version, die mir in der Praxis bereits gute Dienste geleistet hat:
# 000 [short title of solved problem and solution] * Status: [proposed | rejected | accepted | deprecated | superseded by [ADR-005](005-example.md)] * Deciders: [list everyone involved in the decision] * Date: YYYY-MM-DD Technical Story: [description | ticket/issue URL] <!-- optional --> ## Context and Problem Statement [Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] ## Decision Drivers <!-- optional --> * [driver 1, e.g., a force, facing concern, …] * [driver 2, e.g., a force, facing concern, …] * … ## Considered Options * [option 1] * [option 2] * [option 3] * … ## Decision Outcome Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. ### Positive Consequences <!-- optional --> * [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] * … ### Negative Consequences <!-- optional --> * [e.g., compromising quality attribute, follow-up decisions required, …] * … ## Pros and Cons of the Options <!-- optional --> ### [option 1] [example | description | pointer to more information | …] <!-- optional --> * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] * … <!-- numbers of pros and cons can vary --> ### [option 2] [example | description | pointer to more information | …] <!-- optional --> * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] * … <!-- numbers of pros and cons can vary --> ## Market Adoption ## Consequences ## Links <!-- optional --> * [Link type] [Link to ADR] <!-- example: Refined by [ADR-005](005-example.md) --> * …
Zu guter Letzt
Insgesamt können ADRs dazu beitragen, dass deine Architektur besser dokumentiert, verständlicher und nachvollziehbarer wird. Und das muss nicht immer ein komplizierter, langer Text sein. Das führt nicht nur zu einer besseren Zusammenarbeit in deinem Team, sondern auch zu einer effektiveren Entwicklung deiner Software.
Also, warum nicht heute noch damit anfangen, ADRs in deinem Projekt einzusetzen?
Schreibe einen Kommentar