Standardization at Scale is a Superpower

Standardization¹ means following some sort of convention or rule when organizing code and architectural components within a codebase.

What kinds of things should be standardized?

• Names (variables, components, files, services, libraries, repositories, etc)
• Folder structure (services, libraries, etc)
• Abstractions (similar abstractions should have similar names)

Standardization reduces the cognitive burden when understanding and modifying complex code

This is the most important argument for standardization.

Software inevitably grows more complex over time, and it's impossible to understand a complex system when there's no underlying — or standard — structure to it.

The only piece of code that will never change is the code that's not used by anyone. (Adapted from Bjarne Stroustrup²)

Codebases need to change over time, as engineers and architects learn more about the domain they are modeling. But changes are always risky because things may break and it may disrupt the business.

There are many ways to mitigate risk during changes but it's always easier when the structure of the code that needs changing follows an understandable structure.

If there is some (any) standard, engineers can expect things to be in the same places, and they can better measure the risk and potential impact of changes.

Standardization reduces context-switching cost

If every project in an organization (repository, microservice, library) follows a standard structure, it is much easier for engineers to move from one team to another.

Once someone learns the base structure, it's easy to get up and running in a new team if the codebase is standardized.

Standardization promotes automation

Standardization promotes automation because scripts written for one context will likely also work in all other components that follow the same standard/convention:

• Scripts to check for code quality and style;

• Generators and pre-built templates for boilerplate code;

• Ad-hoc scripts that depend on the fact that all components follow the same structure.

Standardization reduces the harm caused by inexperienced and ill-intentioned coders

Inexperienced (but energetic) engineers may cause quite a bit of harm by overengineering, building overly complex code and increasing maintenance costs. Being forced to work within the boundaries of an opinionated standard helps reduce errors.

In addition to that, ill-intentioned employees may purposefully add complexity to systems they are responsible for, as a insurance against job loss — the codebase becomes so difficult to understand that they are effectively guaranteed a job because nobody else understands it.

Standardization reduces both risks, as it adds an upper limit on the amount of accidental complexity one can add to a system.

Standardization eases AI-enabled refactoring and reasoning

Nowadays (early 2025) there are many AI-enabled tools that can read an entire codebase and make complex modifications such as automatic refactoring, writing tests and answering arbitrary questions about the system.

All AI tools benefit from codebase standardization. They perceive that the myriad instances of a particular pattern help them understand what an abstraction is about, and they are better able to reason about the codebase.

Standardization reduces risk when manually adjusting codebases

Whenever we need to make horizontal changes that affect multiple systems, this will be made much faster and safer if all the affected systems follow the same structure and/or conventions:

For example: Suppose we need to change the way real-time alerts are handled for all microservices in use by an organization. If the service codebase and the alert code are standardized and defined the same way (in the same folders, following the same convetions, etc), it's much easier for someone to change all of them at once, either by automating the process, or doing it manually, but much more efficiently.

Standardization aids in discoverability

Suppose an engineer is exploring a microservice's code to check if products of type foo-bar are handled by that service.

After a quick inspection in the codebase, it seems that there is a products/ folder and there is one subfolder for each type of product handled. Sure enough, there is a folder called foo-bar in there, so the engineer quickly understands that these products are indeed handled by this service.

But suppose the code for handling each product were scattered all around the repository and each of them used a different folder structure, etc. The sheer cognitive effort of understanding what's going on in the codebase will be much more stressful and error-prone.

1: As it relates to software.

2: "There are only two kinds of languages: the ones people complain about and the ones nobody uses."