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
March 21, 2019

Knative on IBM Cloud Kubernetes Service: Your First App… Now Even Easier!

We're excited to bring you a change to how IBM Cloud Kubernetes Service exposes Knative. The process has been simplified greatly and will make your life much easier.

Continue reading

March 20, 2019

Getting Started with the Couchbase Autonomous Operator on IBM Cloud Kubernetes Service

We're excited to be working with Couchbase Server to bring you this step-by-step guide to "Getting Started with the Couchbase Autonomous Operator on IBM Cloud Kubernetes Service."

Continue reading

March 18, 2019

Kubernetes Clusters: Architecture for Rapid, Controlled Cloud App Delivery

Kubernetes clusters are the building blocks of Kubernetes, and they provide the architectural foundation for the platform. The modularity of this building block structure enables availability, scalability, and ease of deployment.

Continue reading