Code Review is an Architectural Necessity: Quality attributes that code review ensures

Share this post:

This post is the second in a series on code review and architecture. Part one is What is code review and what problems does it solve?

The qualities of a system that are valued are called quality attributes. Architecture as a practice chooses from an ever-expanding set of attributes to value when building a “thing.” A quick example of a quality attribute is the “choose any two” trichotomy of “fast, cheap, and sturdy.” Let’s now discuss the key attributes that code review guarantees.

#1: Code review guarantees maintainability

When the authors of a project move on, who will care for the project? People aren’t forever — they advance to other projects or leave an organization. It’s vital that an architecture values maintainability. Let’s talk about that first.

To me, valuing maintainability in an architecture necessitates that engineers write maintainable code: code that can picked up easily and quickly modified by new developers. It also has a design that’s easy for non-programmers to understand. Code Review drives all of these.

a. Learnability

The best way to get someone acquainted with code is to throw them into it, not from the “go make this change” point of view, but rather, “take a look at this real code with me.”

We want them to learn the conventions and patterns of the codebase’s use of the language(s) and frameworks of the project.

We want both the initial developers and the maintenance mode crew to understand the goals of the architecture, and the risks present in the code as is exists today.

With this knowledge, they can deal with problems on their terms. We want them to use the same terminology, too: establishing common vocabulary is necessary to make the project learnable. Code review enables and encourages teachable moments; time when someone’s views are challenged and possibly even changed.

Pairing Modalities Chart, crossing a Learner and Expert when Coding and Reviewing. When both are coding, they're synchronously pairing and teaching. When the Expert is Coding and the Learner is Reviewing, they're engaging in exemplary reading. When the Expert is Reviewing and the Learner is Coding, they're engaging in constructively critical evaluation. When both are Reviewing, they're engaging in serendipitous evaluation of example.

This chart shows the modalities for learning in a reviewing situation. Pairing is great, but we need to spend just as much time reviewing to transfer knowledge to the next generation of engineers. We need to read solid code and we need to read code that can be improved.

The next generation is not only younger engineers; but others taking your place as you advance to a different project.

b. Understandability

It’s vital to ensure that developers on a project understand the architecture and the implementation decisions alike.

While they may not be involved in construction of each decision, code review enables them to be aware of changes and ask questions about those changes as the project evolves. In doing so, they better understand architecture and implementation, and are better equipped to identify deviations from established plans and best practices.

This builds tribal knowledge ripe for passing to others, including executives, and investors in the proverbial elevator.

c. Serviceability

Serviceability focuses on the ability of a technical team to provide support.

Given enough eyes, all bugs are shallow. —Linus’s Law

By exposing new configuration, hiding unnecessary or debugging configuration, and agreeing on use cases that may fall outside of primary architectural goals, code review drives a consensus on what the people supporting the project will be expected to know and do. This also drives documentation.

Problems are more likely to be seen if more people are looking at the source of the problem, and thinking of unintended uses and compensating behaviors.

#2: Code review guarantees compliance

a. Accessibility

Do you have more than one person on your team knowledgeable on Section 508, WAIS, or ARIA, and internationalization and localization standards? Code review not only aids compliance by expert review, but can teach best practices, thereby expanding the number of people who can write code with accessibility in mind.

b. Auditability

Code review drives auditability. You’ve probably heard the phrase, “History is written by the victor.” Well, Git history is written by the victorious commit! Version control shows what changed and the reason for the change, but it does not describe the decisions that were dropped. A code review system preserves those discussions and decisions.

c. Idiomaticity

The quality of using tools chosen for the project in the best way they were designed to be used is called idiomaticity. Ever seen Java that looked like C? Java-style mutable objects everywhere in your Scala? These are violations of the idioms that these tools proscribe. Idiom violations can make for less readable code, and in some cases, less performant code: writing idiomatic code enables the compiler or interpreter produce or run faster programs.

#3: Code review guarantees security

We want to spot vulnerabilities before they ship and teach defensive posture. Linus’ Law, “Given enough eyes, all bugs are shallow,” applies here, too. But the best way to keep out bugs and vulnerabilities in code? Simply minimize unnecessary features. YAGNI: You Ain’t Gonna Need It.

When it comes to security, reviewers are like your lawyer, screening and recommending actions to minimize risk, avoiding preventable mistakes, and establishing a plan for what happens when you’re all wrong.


Code review ensures maintainability by encouraging engineers to write code that meets a consensus agreement: code that can be modified quickly, picked up easily by new developers, and is easy for non-programmers to understand. These quality attributes are all intertwined too: systems that are serviceable are understandable, systems that are understandable are learnable.

In summary, code review ensures at least the following attributes:

  • Maintainability – code of the system can be read and improved
    • Learnability – code of the system can be picked up by developers new to it
    • Understandability – the system can be reasoned about by developers and non-developers alike
    • Serviceability – the system can be supported when there is a problem
  • Compliance – code meets standards and demands
    • Accessibility – the system makes effort to reduce barriers to its use
    • Auditability – changes to the system are tracked and knowable
    • Idiomaticity – the components of the system is are used in the way they were intended to be used
  • Security – the system offers reasonable protection from threats external and internal

This series of blog posts is based on my presentation, Code Review is an Architectural Necessity. It was first shared at SATURN 2016 and subsequently at Github Universe 2016. This content is licensed CC BY-NC-SA 4.0.

More stories
May 7, 2019

We’ve Moved! The IBM Cloud Blog Has a New URL

In an effort better integrate the IBM Cloud Blog with the IBM Cloud web experience, we have migrated the blog to a new URL:

Continue reading

May 3, 2019

Kubernetes Tutorials: 5 Ways to Get You Building Fast

Ready to start working with Kubernetes? Want to build your Kubernetes skills? The five tutorials in this post will teach you everything you need to know about how to manage your containerized apps with Kubernetes.

Continue reading

May 3, 2019

Using Portworx to Deploy and Manage an HA MySQL Cluster on IBM Cloud Kubernetes Service

This tutorial is a walkthrough of the steps involved in deploying and managing a highly available MySQL cluster on IBM Cloud Kubernetes Service.

Continue reading