The process of making changes to code is a routine part of software development projects. However, software developers can sometimes be hesitant to make changes because they are unaware whether a decision that was previously made was carried out in a particular way for a reason. There is a natural fear that any change you make might go on to have unintended consequences. At the same time, it can be difficult to identify or trace the reasoning behind the code architecture.
In this situation, there are a few options that a software developer could take. One is to review any existing code comments or commit messages, for some notes that clarify the development process behind the code. Another solution might be to locate the original work item or speak to developers who are still working at the company. Outside of these options, it may be difficult to find any explanation for the decisions that took place when the code was originally written.
Some team requirements to overcome this problem would be to:
- Record why you as a developer have made that decision at the time of writing
- Make architectural decisions easy to document
- Make sure that architecture decision records are easy to find
By ensuring that it is easy to document the decisions, you are increasing the likelihood of this process being repeated in the future. Likewise, if these decisions can be easily located, then fellow developers will also be encouraged to document their decisions too.
This article will look at how we record technical decisions at Audacia, as well as the reasons behind making technical decisions.
Architecture Decision Records in software development projects
Architecture Decision Records (ADR) are simple but effective Markdown files that can be used to document information about an architectural decision that a developer has made.
Audacia has installed an NPM package that allows developers to quickly create a new ADR by simply adding a title. Once the title is configured, users will be provided with these writing prompts:
# 29. public facing site uses separate database
Date: 2022-09-14
## Status
2022-10-04 proposed
## Context
Context here...
## Decision
Decision here...
## Consequences
Consequences here..
With this basic template, your teams are prompted to include all the relevant information about their architectural decisions. The document can be broken down into these key areas:
- Context: What relevant information do you need to know to understand why the decision was made?
- Decision: What decision was actually made? How have we done something that could have significant consequences in the future?
- Consequences: Some of the consequences that were considered when the decision was made. This section is useful for finding out what concerns the original decision maker had, so that you know what you need to think about if you want to change their decision. This section is equally useful for situations where the original authors haven't considered a problem that you are currently facing.
The size of these documents can vary, but they generally only require a few bullet points per section. Ultimately, the size of these documents will vary according to the situation that has preceded them.
The Markdown format of these files makes them easy to customise. This flexibility allows for amendments to be easily made or, alternatively, for new subsections to be added.
For example, an author may decide to include an ideas section, which could document further suggestions around a decision that a future developer could reference and build upon.
The inclusion of links is also a neat way to tie multiple documents together and provide further context for the decision. All of these documents are stored in a folder within the codebase.
How we use ADRs in software development projects at Audacia
Audacia has primarily documented development decisions in ADRs. In this vein, we advise against using ADRs for general housekeeping. The records should, instead, be reserved for architectural and technical decisions where the consequences of this decision will impact the project for a long time to come.
However, there have also been scenarios where other teams have benefited from these files. For example, Audacia software testers have their own repository which contains ADRs that document how the teams have changed the way that they carry out Cypress automation testing.
We also anticipate that these documents will come in useful when a project moves into support and maintenance. Support teams, by definition, do not have the full commercial background or the history of a project. These documents are valuable for support team members because they will help them to understand the rationale behind certain decisions and, therefore, allow them to make their own informed decisions when carrying out essential support and maintenance.
Case Study: A global agricultural processor and food ingredient provider
Audacia has been using ADRs on one of our longstanding projects with a global agricultural services provider. Prior to implementing these documents, our development team had encountered a few instances involving existing solutions where knowing why certain decisions were made would have been beneficial.
From this position, we looked for a solution that would provide adequate visibility for future development teams. It was at this point that we began using ADRs. Introduced just over six months ago, there are now 22 records that have been created and are available to the project team.
From our experiences creating ADRs, we believe this to be quite a high number of records; something that is reflective of the amount of technical work that has been completed recently.
A clear explanation
While ADRs may not be required for all projects, writing them can be a useful way to provide a clear explanation of why certain architectural decisions were made. These documents can provide that much needed clarity for when product owners and development teams change.
Overall, these documents are a supplement to developers when they are coding and making their own development decisions. Audacia intends to continue using ADRs when documenting architectural decisions where appropriate on all projects.
Audacia is a software development company based in the UK, headquartered in Leeds. View more technical insights from our teams of consultants, business analysts, developers and testers on our technology insights blog.
Technology Insights
This article was developed from a talk delivered by Audacia Senior Software Developer, Tim Hilton. I would like to thank to Tim for providing his expert insight during the development of this article.
