Understanding the Importance of Choices in Software Design 

Creating high-quality software is a challenging task. Surprisingly, crafting or maintaining even low-quality software is no walk in the park either. With every line of code we write, we make choices. Some of these choices bear a significant impact, while some are critically important.  

Although we can adjust some decisions with relative ease, there are others that are difficult to alter. Probably the best-known definition of software architecture says, “Architecture is the stuff that’s hard to change later.” 

So, the decisions we make regarding our software architecture tend to stick with us because they are difficult to change. However, before we decided to pursue a specific path, we had thoroughly considered and discussed it, meaning we had valid reasons to choose that direction, right? Now, if we are considering a change in course, do we still remember why we made those initial decisions? Were there alternative options that we evaluated before settling on our chosen path? 

The Second Law of Software Architecture 

In their book Fundamentals of Software Architecture, Neal Ford and Mark Richards define Second Law of Software Architecture as “Why is more important than how.”

Indeed, it is essential to strive for well-informed decisions. Understanding the rationale behind our choices allows us to reevaluate them when needed and retain valuable knowledge. Consequently, thorough documentation becomes imperative to preserve this knowledge for future reference. 

BM Insight: For the sake of my sanity, I will also mention the First Law of Software Architecture: “Everything in software architecture is a trade-off.”  

Architectural Decision Records: An Insight 

One effective way of documenting architecture decisions is through Architectural Decision Records (ADRs).  

In general, the ADR concept consists of Architecturally Significant Requirement (ASR) and Architectural Decision (AD).  

An AD represents a software design choice addressing either a functional or non-functional requirement of significant architectural importance. An ASR is a requirement that has a discernible and quantifiable influence on the software system’s architecture and its quality. The ADR serves as a detailed account of a single AD, capturing its rationale. The comprehensive collection of ADRs, which are developed and kept for the duration of a project, forms its decision log.  

Challenges of Architecturally Significant Requirements 

Defining ASRs can be a daunting task. These requirements often lack precise expression, making them initially challenging to identify. They might be concealed within broader requirements and subject to varying interpretations depending on the context.  

Moreover, architecturally significant requirements are subjective and dynamic, adding to their complexity. 

While other requirements could share some of these characteristics, what sets ASRs apart is their unique importance and impact on the overall system’s architecture. This significance makes dealing with these requirements particularly intricate and demanding.  

Key Components of an ADR 

ADRs typically include the following information for one architectural decision: 

• Title: A clear and concise title that reflects the essence of the decision. 
• Context: The situation or problem that prompted the need for a decision. 
• Decision: The specific choice made to address the given context or problem. 
• Rationale: The reasoning behind the decision, including the benefits and drawbacks considered. 
• Consequences: The expected outcomes and potential impacts of the decision on the system and development process. 
• Status: Indicates whether the decision is proposed, accepted, rejected, or superseded. 
• Date: The date when the decision was made or recorded. 
• Author: The individual or team responsible for the decision and its documentation.

Preserving the Integrity of ADRs 

Once made, an ADR typically is not altered. If a decision is changed, a new ADR is created to supersede the old one, preserving the history of architectural decisions. 

It is a good practice to store ADR in source control together with the code/project. 

A Practical Glimpse: ADR Example from Neal and Mark’s Book 

For last, we will show you example of ADR taken from book written by Neal and Mark: 

BrightMarbles’ Commitment to Excellence 

At BrightMarbles, we strive to uphold the highest standards, continually integrating best practices such as the use of ADRs. Our rich experience, shaped by years of dedication, is currently being channelled into the Raven project. This endeavour is not just an investment, but a showcase of our commitment to efficient, reliable, and innovative software design. 

BM Insight: Software architecture is the umbrella term for various approaches, models, methods, and programming languages that make a comprehensive software development project. In our daily coding errands, not only that we follow current industry trends, but we also eagerly study how we got here. One of our previous posts, The Genesis of Object-Oriented Programming, is a thorough analysis of the development of the eponymous programming model. As pointed out before, we need to know why to become versatile conceptual software engineers.  

In Conclusion: The Vitality of Architectural Decisions and ADRs 

In the multifaceted realm of software architecture, our choices, and the rationale behind them, are pivotal. These choices, whether easily modifiable or steadfast, have lasting repercussions on our software’s performance and maintainability. Architectural Decision Records emerge as the beacon, providing clarity, rationale, and a historical account of our architectural choices. They not only fortify our architectural framework but also ensure that the wisdom behind each decision remains accessible for current and future team members.  

As highlighted in the BrightMarbles’ relentless pursuit of excellence and best practices – like the ADR – one thing is evident: the intricate dance of decision-making in software design isn’t merely about choosing a path but understanding, documenting, and justifying the why behind it. As developers and architects, embracing tools like ADRs helps us navigate the complex waters of software design with precision, clarity, and foresight. 

About Author: 

Nenad Stojkovic is a seasoned software architect and a tech excellence officer at BrightMarbles, and a PhD student at the Faculty of Sciences in Novi Sad. He’s an all-round language enthusiast and learner, whose scope of knowledge extends beyond programming languages, to English and German. Music is the fourth language he speaks, and while his guitar gently weeps, Nenad travels the world, admiring the amazing works of architecture.