Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
Architecture Decision Records will save you from guessing. Have you ever worked on a codebase and wondered why you were using a particular library/framework, applying a pattern, or deploying a particular way? If you ask a teammate and they also have no idea because that was defined before them as well. Is the decision still relevant for the current context? What was the context when the decision was made? A lot of this is institutional knowledge that is lost, leaving you guessing. Instead, capture Architecture Decision Records along with your code in the same repository. It’s a log of all the decisions made along the course of a project/product.
YouTube
Check out my YouTube channel where I post all kinds of content that accompanies my posts including this video showing everything that is in this post.
Institutional Knowledge
There are generally two phases that personally go through when looking at code that I’m not understanding its purpose.
The first phase is the “I’m an idiot” phase where I don’t understand something and assume it to be correct. This could be how something is modeled, how a library is being used, or just anything that I see that is intriguing. I assume the reason why something exists makes sense. It must be correct. The benefit of the doubt is given to the original author of whatever code I’m looking at.
The second phase is the “This is terrible” phase where I believe something is wrong and that my assessment of what it should be is correct. My plan at this point is to change whatever it is I think is incorrect.
Once I come out of this second phase, I come to my sense and realize that I have no context on why something is the way it is. Without context about how decisions were made at the time, both phases I described above are incorrect.
In phase one, I can’t assume the context now is the same as the context was when the decision was made. Doing so would be accepting the status quo. In phase two, if I decide to change something, there could be a very good reason that isn’t trivial for why the decision was made.
In either situation, I don’t understand the context of the decision when it was made at the time.
Software evolves, especially software products that can have a very long lifespan. Decisions made by developers and/or architects that may no longer be involved in the product/project anymore. Or perhaps they no longer even work at the company anymore. Institutional knowledge will be lost and your ability to understand the context can be very limited.
Architecture Decision Records
A solution to losing this institutional knowledge is to record decisions in a lightweight fashion. Michael Nygard posted about documenting architecture decisions which described a format to what to capture. The basics are a Title, Context, Decision, Status, Consequences.
Here’s a template using the proposed format.
When you create an ADR, you store it alongside your source code. Within the same repository. This could be in the /docs/adr/ of your repository. If you want to reference in code comments to a specific ADR, have at it!
Be pragmatic about these records. If you want to record other information not listed in the template, do so. If you don’t need status, don’t use it.
When a decision is made, create an ADR with enough information that someone not involved in the decision would understand. Write ADRs for future readers.
You can simply create new ADR markdown files manually, but if you prefer using a tool you can use the adr-tools scripts to create new ADR files and supersede existing ADRs.
Example
Here’s a sample Architecture Decision Records that I’ve created about using a messaging library or using the SDK directly of a message broker.
Architecture Decision Record Log
Hopefully, you can see how Architecture Decision Records provide a log of decisions. A log living alongside your code in the same repository can give context to decisions that were made throughout the life of a codebase.
This isn’t documentation, the is a historical log. This allows you to go back in time and read your ADRs to understand how you got to where you are.
Source Code
Developer-level members of my CodeOpinion YouTube channel get access to the full source for any working demo application that I post on my blog or YouTube. Check out the membership for more info.