The missing document in your GitHub repository — Architectural Design Decisions

Trying to understand a GitHub repository is a pretty interesting adventure. You open a repository and then if you are lucky to find a decent Readme file you discover the technologies the project was built with, how to setup and start the project etc.

“Oh nice, the project is using Node.js and i can start it up with NPM! Everything is in the readme file!” — Naive Programmer

After you go through the Readme file, and Wiki’s you usually start digging through the code to understand how it’s built.

However, there is one key question and answer missing in the average Readme file or Wiki — Why?

Such an easy question, but unanswered in most projects.

In this article i will introduce ideas and examples how to answer that question.

Why was the software designed as it is? what non-functional requirements influenced the architecture? how are those decisions mapped to the problem space and the requirements?

The importance of Why in Software Architecture

Software architecture is a process; a sequence of strategic design decisions mapping specification and business goals to architecture design

Software architecture can be an explicit or implicit decision-making process, but regardless of the approach, every system out there has a software architecture and decisions were made based on a specific value hypothesis that is supposed to satisfy known requirements.

Traditionally software architecture is concerned with functional and non-functional requirements (really bad name) and converting them into a set of design decisions that inform the architecture.

However, that is not all. Software architecture artifacts are also a method of communication. They are a way to increase understanding and alignment between team members.

People associate software architecture with complex diagrams and documentation, but that is not what i’m talking about in this article.

I want to suggest using a very lean artifact that you can produce and maintain easily in Github— A “design decisions” checklist.

This checklist document reasons why you decided to go in a specific direction with your architecture. It’s a powerful communication method that allows you to think and communicate in a structured way.

Design Decisions — An Example

Here is an example adapted from the original Node.js whitepaper by Ryan Dahl from 2009:

Node.js Design Decisions - a.k.a. Why?
This is a list of design decisions to support version 0.2 of the Node.js library

Maintainability
 We want to make it simple to work with asyncronous IO
 No function should direct perform I/O. Use callbacks instead
 Have built in support for important protocols (TCP, DNS, HTTP) and support many HTTP features (chunked requests, keep alive, comet etc.)
 The API should be both familiar to client-side JS programmers and old school UNIX hackers.
 Be platform / operating-system independent
 Reuse solid platforms (Google V8) and minimize dependencies (python only)
 Use JavaScript since it's designed to be used in an event-loop
Scalability
 I/O needs to be done differently from traditional systems. Other threads of execution should run while waiting. We are inspired by NGinx and the event loop.
 Stream everything; never force the buffering of data
Note: These decisions are copied from the original Node.js paper by Ryan Dahl and adapted to this format.

I believe that once you read the design decisions above it’s much clearer what is the goal of Node.js and why Ryan Dahl choose JavaScript and the event-loop when he designed Node.js.

Very few projects clearly articulate why they do what they do, and that is the missing part.

Imagine having a nice checklist like above in every project in GitHub! It would be a delight to understand and contribute to projects.

Prevent current and future religious wars and rewriting

What is the first thing a programmer does when he doesn’t understand a project architecture after a few days? he thinks about refactoring it or rewriting it.

Having a clear design decisions document is a way to explain why the system was designed the way it is and to articulate specific trade-offs that you made.

Sometimes it’s hard to maintain all quality attributes on the same level. For example it’s well known that focus on high performance and scalability must be paid by having lower maintainability. That is a common tradeoff, but if not documented it could be misunderstood by looking at the code alone.

“Why is he using this queue in the code? WTF! this programmer is an idiot. I must rewrite this code” — Clueless programmer

If decisions are documented in a document it’s easier to understand and there is a lower chance that the next developer will curse you at night. Design decisions shed light on the most complex parts of the architecture and help the next developer live a happier life.

Programming religious wars often start out of misunderstanding and you can prevent it with transparency.

Be honest about your decisions

Design decision documents provide a nice level of honesty about your software architecture for your future self or people coming after you to maintain the code.

Sometimes you are making tradeoffs for the sake of productivity or delivery, and that is completely fine as long as you document it.

For example, a really well known approach in building startups is to use the technology you are mostly familiar with, which is not necessarily something that a corporate software architect would understand and approve.

A developer that is not familiar with this mentality would be really surprised to open a GitHub repository and discover that Ruby on Rails was used for system X even if it is clearly “not scalable”, but there could be a way to document the decision to make it understandable to the puritan software architect. Here is an example:

Project MVP - Design Decisions - a.k.a. Why?
This is a list of design decisions to support the MVP of our product.

Maintainability
 We prioritize productivity and time to market, so we plan to use Rails since the team is familiar with the technology even if it might be suboptimal.
 Skip automated tests because of lack of time and money for the MVP
Scalability
 We expect from 500-2000 active users using our systems daily. This should be easily achievable with a modest deployment in Google Cloud and Kubernetes.
Performance
 We want to have < 1s response times on every page in our system
Fault-Tolerance
 Our systems should restart automatically in case of a failure. We plan to use Docker and Kubernetes.
Security
 Our systems should be protected against the top 10 OWASP vulnerability

Honesty is nice, and it can save face and refactoring for many. You can even go a step further and include the things You planned to incorporate in your design but you didn’t have time to.

A good guideline to structure the checklist is to follow common system quality attributes. If you want to go an extra mile, you can can even split the design decision document in two sections: Non-Functional requirements and Design Decisions. However, brevity is always a winner since nobody likes to read long documents.

Chapter 16: Quality Attributes

The point of keeping these documents in GitHub and not in Confluence and similar documentation systems is that documentation gets old and usually ends up not being maintained. By keeping it simple and lean in GitHub markdown files there is a higher chance to survive passage of time and keep the document up to date.

ADR’s

For the more advanced practitioners of architectural decisions documentation, ADR is a project that is trying to standardize documenting and maintaining architectural decisions in your repositories.

A “lightweight” ADR consists of title, status, context, decision, and consequences

For further reading check out their website:

https://adr.github.io/

Conclusion

I believe that having architectural design decisions in GitHub repositories would make programming much more enjoyable and would increase understanding and ability to learn how to maintain unfamiliar projects. It could also be very useful for open-source projects.

Since most of programmer lives are spent maintaining existing code (and not writing new code) i believe that it is important to think about making it a bit easier for everyone involved. Help yourself and your colleagues succeed!