During software developing we often have some questions, especially when we join existing projects: why app uses that language? Why these solutions? Why we handle time or money values in such way? All these questions are very important, because it is a part of application architecture. Of course we can on team knowledge, but such method is not efficient and not possible to maintain on larger projects and when we want to scale up: new people will join, but some people will also leave project. Important knowledge distributed partially to different people will be hard to get. The solution is ADR: Architecture Decision Record.
Architecture Decision Record is just a document with information about why and when team decided to use some solutions. It can describe additional context and consequences of adopting the decision. In effect, we have one, central place with all required knowledge, with history and detailed descriptions. It helps during onboarding new people, because they can check ADRs quickly. It helps if we lost some project members, because we will not lost important knowledge. It also helps if we make changes on some modules ownership, introduce internal structure changes, because we still everything important in one place. Finally, it allows us to such documents in code, explain why we make adjustments – everything is clear then.
Table of Contents
When should we create ADR?
As soon as possible. It is long-term solution – we will not see positive effect immediately, but after some time, it will help us. More detailed question: should we create it only for bigger things, or also smaller? It is flexible. We definitely should describe bigger decisions, in smaller it depends how they will impact our application. We can start to write ADR when we have a problem, even if we do not have any solution for that problem: it allows us to aggregate potential options, then discuss and finally decide and approve the best approach. In such case, we will have clear history what prompted us to make this decision.
ADR example
There are many different patterns of creating ADR and there is no right answer for question “which one should I use”. It depends on your needs, application structure,
NUMBER – ADR NAME
Status
(…)
Date
(…)
Context
(…)
Decision
(…)
Consequences
(…)
And real example:
1. Use standard HTTP response codes
Status
Approved
Date
26/02/2022
Context
There are many possible options to send responses – even if action will fail (for example we cant find model), it is still possible to send completely different response code (example: 200 OK). We should avoid that and make all responses clear, predictable and easy to interpret: we can use our rules, or follow global HTTP recommendations.
Decision
We decided that we will always use only valid, recommended HTTP response codes, for example 403 if access is forbidden, 404 if we will not able to find model etc.
Consequences
– All new endpoints will return only valid codes
– We will not accept custom or invalid response codes on code reviews and merge requests
– Legacy endpoints will be updated during required refactors
Where should we store ADRs?
Similar to how should ADR look like, there is no simple answer, but there is the same rule: you should define one place and use it for all ADRs. You can store them on repository and make close to code, you can use shareable notes, cloud with just txt files or anything else. The important part here is: you should backup your ADRs (or service you will use should offer that) and also, it should be possible to share ADRs for read-only. It’s required if you want to link to them in code comments, tasks descriptions or other architecture considerations.