How to persist project decisions for future developers and why you should add ADR to your project?

ADR is an Architecture Decision Record, but if we leave it like that, it won’t tell you anything. So let’s deconstruct the name into smaller pieces.

Deconstructing ADR

Architecture Decision

I like to describe it as: “Every decision in the development team that has an impact on the state of the application and the way of working in a particular time”.

Ok… we have it, but here are some examples:

  • Use TypeScript and React on the frontend
  • Create backend in .NET
  • Create the application for a cloud. Try by agnostic if you can, but currently, we will use AWS
  • Let’s use Feature Toggles

The above decisions are simple, but usually, we need to decide something in the middle of the project. For example:

  • New frontend files should be created in TypeScript and if you touch a JavaScript file, then migrate it to TS and add typings
    • The decision can be made when a current app is in JS and when we want to start migrating to TS, but without stopping current development
    • The decision can be connected with a different one about ongoing refactoring
  • Stop using MomentJs, start using date-fns
    • The decision can be made when devs discover that MomentJs is no longer supported

But some decisions can be not so technical. They can be about the way of working:

  • Use Trunk Based Development instead of GitFlow
  • Every merge to master should be reviewed on CodeReview

Record

It is a place for one document, ADR in our case.

But we should have also ADL, Architecture Decision Log it a place where we store ADR documents.

Why we require ADR

When we know what is ADR, we should be aware why we need it.

  • It forces analyzing multiple options and alternatives. It is good, because it allows us to decide better.
  • We have to consider pros and cons of that decision. There is no decision with pros only. It is good to know what can go wrong with it.
  • It initiates constructive conversations and interrupts worthless discussions. When we create a certain ADR, then a lot of discussion are required to be done to make every team member happy. But after it, everything is known and we stop wasting time on discussing about spaces and tabs.
  • It allows future developers to understand what decision was made, what was the context. So they will have better understanding of the code, and they will know limitation from the past.
  • It allows introducing new developers faster, because a lot of knowledge is in ADRs. So they will be able to understand architecture easier
  • It allows going in straight destination, because a lot of topics and ideas are shared there

What should it contain

There are a lot of items that should be in one ADR. Some of them are mandatory, some of them are optional:

  • Title
    • It’s obvious
  • Date of creation of the decision
    • It allows people to know when it was created to have better context
  • Context
    • A description of current situation. Every decision has a context, so it is a must. Allow people in the future to understand your current situation.
  • Status
    • Every decision has a status. It can be Accepted, Rejected, Canceled or a Draft.
  • Alternatives
    • To show people that you have considered alternatives and describe what they weren’t chosen
  • Pros and cons
    • Every decision has advantages and disadvantages. Describe it. It allows people in the future to respect that decision.
  • Decision
    • The most important part. Write what is the decision.

ADR format

They are different approaches what is the best format of it, but I would suggest you:

  • Don’t create your own standard. Use a standard one, and keep it simple
    • I recommend MADR
    • If you need something different, check it on GitHub
  • Keep it in the same repository as code
    • You will have a history
    • You would be able to discuss in standard way (Pull Requests)
    • No one will search it
  • Use Markdown
    • It is easy to write
    • It is easy to read
    • It is easy to generate a webpage based

At the end

I am sure that in every project you are, a decision like that muse be done.Make sure that it will be written as ADR. It doesn’t cost a lot, but saves a great amount of time.

What do you think about ADR? Leave a comment below.

comments powered by Disqus