Anyone Know Why It’s Like This?

DZone 's Guide to

Anyone Know Why It’s Like This?

Too often, code is poorly documented or there wasn't enough communication between dev teams. Is it possible for Architecture Design Records (ADR) to help?

· Agile Zone ·
Free Resource

In a previous article, I wrote about an aspect of developer to developer communication via documentation.

I am going to continue that theme in this article, by putting forward two scenarios and seeing if they can be answered to an extent with ADR (Architecture Design Records).

Scenario 1

You join a team that is maintaining and/or adding features to an existing application or set of applications.

You get access to the codebase and are maybe also directed to some documentation residing in an external location (say, for example, a Wiki).

The externally located documentation contains general information about the application, with the source code, and asking your teammates is the main means of understanding the application(s).

A potential, and common, thought is, “why is the application like this?” The question can refer to the structure of the code, the frameworks used, the language, specific dependencies, and so on.

It should be noted that posing this question doesn’t necessarily imply a judgment, rather it is a matter of curiosity and a marker for how future features should be developed.

The difficulty in answering the question can come in the following forms:

  • Your teammates were not the original authors.
  • No one really remembers why.
  • It was a strong developer’s preference and no one else had a valid counter argument.
  • The team was quite large in the beginning, so even though some of your teammates were there from the start they were not necessarily privy to the various decisions that were made.

Scenario 2

You are in a team of developer’s that is large enough to create sub teams. In such teams, it can be hard to be aware of everything that other sub teams are doing.

As developers come and go the various components/modules of the application start to change. In some cases you know why, and in others, you may not.

For example, the front-end sub team may have started to build it using a particular approach (e.g. JSF), but a change in developers resulted in an alternative approach (e.g. ReactJS).

In this example, for some people, the switch from JSF to ReactJS was obvious, but maybe not to everyone, even if the transition was verbally communicated.

Another example could be that you need to create an API that other systems can call. Developers on the team have previous experience with building REST APIs, but instead, the decision was made to use RPC.

The hope in this scenario is that there will always be someone who was present when the decision was made, and is still around, to answer the question of why a decision was made.

Potential Pitfalls of Not Documenting Important Design Decisions

The most obvious concern of not documenting important design decisions is that there is no record of why things are the way they are.

Should one continue in the same fashion or start changing things? It’s hard to know the answer without any history to refer to.

Another concern is that it may lead to a “brain dump” of information on something like Wiki.

For example, the project is coming to an end and before most of the developers leave, there is a “panic” to write down everything they know.

How good or contiguous is this “after the fact” documentation?

A further concern is the empty Wiki pages that have just a title or the text “coming soon,” where there was an intention to document something, but either no one got around to it or simply didn’t know what to write.

I don’t claim to have the answer to what I have written so far, but the aim of this article is to look at the potential of ADR in addressing this issue for posterity.

Parts of an ADR

The linked article provides details of the various parts of an ADR, but below is a quick synopsis, if you haven’t read that article.

NUMBER. TITLE (e.g. 1. Record architecture decisions).

Date: 01-Aug-2017.

Status: Proposed/Accepted/Superseded by/Supersedes.

Context: The circumstances that require a decision.

Decision: Concrete answers to the above context.

Consequences: The circumstances after applying the decision.

Made by: Names of people who were involved in creating this ADR.

If you read the linked article you would have noticed that there is no mention of Made by.

I added this to my own records as I wanted a means of knowing who was part of the design decision.

This is certainly not present for finger pointing or back slapping, but rather a means of knowing who to talk to, should one seek further information.

Trying Out ADR

It’s not possible for me to write anything about ADR from previous experience as I do not have any.

The point of this article is whether ADR is something I should use in my next project.

The best I can do (and I do recognize that this is also “after the fact”) is to revisit an existing project, go back in time, and create various design records to show what it could look like if I had documented decisions at that moment.

The ADRs are stored in source control with simple markdown. Here is an example:

# 2. Use clean architecture

Date: 15-July-2017

## Status


## Context

We need to distinguish what our application does versus how it does it.

## Decision

We will use clean architecture to ensure a clear separation is maintained between what and how.

See README.md for details. 

## Consequences

Easier to reason about the application.

Easier to replace segments of the application without impacting the rest.

## Made by

Mahan Hashemizadeh

And another

# 4. Documented API

Date: 25-July-2017

## Status


## Context

We need to build an API that other systems can use.

The API needs to be documented so other developers are not spending time asking how to use it.

## Decision

We will use Spring HATEOAS to produce a navigable REST service.

Along with this we will use Swagger to generate documentation about our REST services.

## Consequences

Consumers use the navigable links to acquaint themselves with what calls our services provide.

They then use the Swagger documentation to make sample calls.

Any questions about our services are no longer basic "how do I do this?" questions.

## Made by

Mahan Hashemizadeh

If you like the idea of generating records using a tool then check out this GitHub repository.

I personally just created them by hand, but the above repository was helpful in providing example records.


My current impression is that using ADR can help a team understand why things are the way they are.

Another benefit is the act of writing down the various parts of an ADR can help the decision makers reinforce/reassess that this is in fact how we want to proceed.

If there is too much information in them, then there is the danger that they will be ignored or skimmed over. So, it’s important to keep them lightweight.

I for one will certainly be using this in my next project, and in a year's time, I hope to revisit this article, to see if what I have written still holds true.

archiecture ,design decision ,documentation

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}