Why developers need to track their architectural decisions
February 14, 2020 [ Projects ]
The situation when developer is blaming the code and shouting: “Who the hell created this? Why we use XYZ library but not ZYZ? Let’s rewrite everything with RRR.”. This is familiar to most of the developers who are working on the large product. To avoid such kind of the questions and situations and to be able to give the reasonable answer it’s good to document all the decisions been made.
Architectural decision (AD)
In few words AD is a decision that could be hard to make and then costly is to change. When a new project is creating the decisions for example could be: what technology stack to use or what business logic layer should contain, etc.? Each AD describes a design issue for which several solutions exist. AD contains a decision result (often collaborative) that clearly explains why this or that decision was made.
AD could be captured in many different formats. One completed AD is called an architecture decision record (ADR). ADR is a document, a building block used to write ADs. The set of multiple ADRs forms architecture decision log called ADL.
- AD: architecture decision
- ADR: architecture decision record
- ADL: architecture decision log
Capturing ADs
There are multiple ways how AD could be captured. This could be a spreadsheet in a google drive or inside a code repository. There are plenty of different formats and layouts to doing this.
I’m not going to invent the wheel and show the simplest and fastest way anybody could start from. ADRs going to be stored along with a code.
As a template I will use the first one and default for adr-tools: ADR template by Michael Nygard.
ADR template by Michael Nygard
Let’s look more close on the template itself:
# Title
## Status
What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
## Context
What is the issue that we're seeing that is motivating this decision or change?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?This simple template allowing developer to store a single documented decision.
Up and running:
To manage ADRs there are some tools available. In this example I will use adr-tools.
- Install adr-tools
brew install adr-tools- Create an ADR directory inside your project where you want to store ADRs.
adr init doc/architecture/decisions- Now lets add first ADR:
adr new Create new frontend project with Create React AppNow in the initial directory first ADR appeared with name 0001-name.md
This file has written in markdown and contains a template that you need to fill.
- Now you could generate a TOC (table of content).
adr generate tocAfter you generate a TOC it could be inserted into README.md or CHANGELOG.md for example.
Conclusion
With ADR now it’s possible to look through all of your decision history. This is useful in a way to understand the project architecture and to stay up to date with the general developing path.
Of course there are much more possibilities, approaches and libraries for you so you could try different templates and find what is suitable to your project.
The goal of this article is just to let you know that something like this is exists and the basic understanding how this could be used.