You need to start writing Architecture Decision Records

If you write software, you need to start maintaining Architecture Decision Records (ADRs). ADRs roughly fall into the category of Developer Documentation. They aren't aimed at the Users of the software. Instead, they are aimed at the developers and maintainers of the software. They usually contain information about the layout of the package and what the code does. ADRs, in this context, are an absolute necessity. By definition, ADRs are simply a Record of a Decision that has an impact of the Architecture of the application. In fact, Any meaningful technical decision made in a software project, irrespective of whether it has an impact on the architecture of the application, needs to be documented.

I first came across ADRs in Chapter 17 of Fundamentals of Software Architecture book. A few of us (at Enthought) read this book earlier in the year and ADRs are one of the things that we took away from the book. You can find more information on ADRs here and here.

Here's what the format of an ADR looks like, adapted from Ch. 17 of the FoSA book I linked earlier.

Title: Short description stating the architecture decision
Status: Proposed, Accepted, Superseded
Context: What is forcing me to make this decision?
Decision: The decision and corresponding justification
Consequences: What is the impact of this decision?
Compliance: How will I ensure compliance with this decision?
Notes: Metadata for this decision (author, etc.)

That's just a recommendation and we don't strictly enforce the use of the above format. In some ADRs, a "Compliance" section doesn't make sense as there isn't really anything that the project needs to continually comply with. In other cases, the only "Consequence" of a decision was the need to enforce future "Compliance" so we ignored the "Consequence" section.

For example, an ADR contained the decision to adopt mypy into a project. We documented why we were adopting it, how we planned to ensure that the team complied with this decision and added additional notes like the fact that we needed to rely on third-party stub packages for third-party Python packages.

Another ADR contained information on our approach to paths in the application. We documented the decision to only work with pathlib.Path objects internally and convert string paths to and from pathlib.Path objects at the periphery of the application i.e. in the I/O and/or UI layer of the application. This might sound familiar to you if you've used the Unicode sandwich approach before.

In another ADR, we documented why we chose to go with Python Library A over Python Library B and documented the consequences of this decision e.g. Library A is feature complete but less maintained when compared to Library B so we would have to keep an eye on code rot in Library A.

In some cases, we've chosen to drop the A from ADRs i.e. write Decision Records for any meaningful decision in a software application, even if it doesn't impact the overall "architecture" of the application.

Like I mentioned in the beginning, more often than not, developer documentation talks about what the code does but not why the code does what it does. The "Why" ends up getting buried in Git commit messages, PR descriptions and review comments. You might not need to know the "Why" but when the time comes, knowing the "Why" is how you ensure that you're making the right decision.

Have you used ADRs? Do you find them useful? If not, why?

Popular posts from this blog

Arxiv author affiliations using Python

So, I wanted to get author affiliation information from papers on arXiv. arXiv provides with an API to bulk query their database and get information. Following that, I look for the attribute 'arxiv:affiliation' in the html data. Here's the code - import urllib from BeautifulSoup import BeautifulStoneSoup   url = 'http://export.arxiv.org/api/query?search_query=all:astro&start=0&max_results=1000'   data = urllib.urlopen(url).read() soup = BeautifulStoneSoup(data) #print(soup.prettify()) #list = soup.findAll('arxiv:affiliation') #for i in range(len(list)): #        print list[i].contents   test = [tag.string for tag in soup.findAll('arxiv:aiffiliation')] Now, the problem I'm having is that I'm getting affiliation of all authors which I want to split into sets of affiliations of authors of a paper, which I'm stuck on at the moment. Once I get that part, I can move on to the next part of this pet project, displaying these
Read more

Farewell to Enthought

I started my professional career at Enthought , at the Pune office in India, on Feb 29, 2016. Over the course of eight long years, I spent time at the Austin office in the US, the Cambridge office in the UK, and I worked remotely from India. I was let go on March 27, 2024 . I had an unbelievably great time. I had three amazing mentors - Pankaj Pandey, Senganal Thirunavukkarasu, and Mark Dickinson. Pankaj mentored me in my first year at Enthought. I started paying attention to the craft of software after working with him. Senganal started mentoring me in my second year at Enthought, and continues to mentor me, even after the both of us have moved on from Enthought. He instilled professionalism in me, ensuring that the code I wrote produced precise scientific results, and that I tackled the known unknown aspects of a project first, to ensure timely communication about project progress. I was eager to manage people at the time and Senganal made me realize that I didn't want to manage
Read more

Elementary (particle physics), my dear Watson

Ground Control to Major Tom:  Shruti Patel checking in. Since my dear friend and fellow-physicist Rahul Poruri is homeward bound, and shall remain there for a week, I'm stepping in to continue his tradition of daily posts to Astronut . Even as I write, I'm not quite sure what this post is going to be about, so please forgive me for occasional rants and digressions.  By the way Rahul, I totally resent you for the name of this blog- I'm never going to start my own blog because there's no way I'll come up with a name as cool as Astronut! For now, I shall try and be happy with being a guest writer! Before I begin, a little bit on who I am and what I do; so that you can trust that my general views on science- particle physics in particular- are not entirely baseless. I graduated with a masters in Physics from IIT Madras in July this year, and I'm currently working towards (an eventual) PhD with the Theory Group at the Deutsches Electronen-Synchrotron (DESY)
Read more