Why Code Consistency is Important

Why Code Consistency is Important

When it comes to your codebase, one of the most significant indicators of overall quality is consistency. Consistency of patterns, style, naming, libraries — every part of your system needs to be considered, and carefully designed with consistency in mind.

Why is consistency important?

Consistency is crucial when it comes to code quality because consistency leads to predictability. A solution with a high degree of quality will be predictable in the way it functions. You will be able to look at code, and without any domain knowledge, you should have a pretty good idea what’s going on. To quote Robert C. Martin — author of the excellent “Clean Code” — “You know you are working on clean code when each routine turns out to be pretty much what you expected”.

Many aspects inform the predictability of the code. One of the most commonly focused aspects — with good reason — is tests and testability. Tests can be considered the ultimate manifestation of predictability. They describe the behaviour of the code to the reader in a reliable way. It provides predictability in the extreme, which is why tests are so valued.

Consistency has a similar effect. When your code has standard naming conventions, consistent indenting and spacing, and standardised architecture and interface, It is easier to work with and can be developed faster, and with greater confidence.

How can consistency be improved?

There are several vital factors which you can focus on when it comes to improving code quality through consistency.

Spacing and Indenting

This one might seem reasonably benign — especially in languages like PHP and JavaScript where the spacing and indenting don’t have any functional impact — but do not underestimate the benefits of well-formatted code. When code is formatted consistently, the readers get the advantage of being able to read and understand the code with greater ease. This benefit is the same one you get when you read a well-structured webpage or article. The visual flow of information — while not affecting the content directly — changes the way the data is perceived and ingested. Consider this first example:

JavaScript without whitespace and indenting

A simple example, but already we can see that with the formatting stripped away, it is hard to read at a glance. Let’s see what happens when we add some spaces.

Just like syntax highlighting, spacing and indenting can convey meaning. It can tell the viewer about how the code they are looking at will behave, but only if you let it. This aspect of code style is very subjective, so work with your team to find a spacing and indenting style which everyone is happy with, and strictly enforce it with tools like eslint, or whatever linting tool supports your language of choice.

Variable Naming and Casing

There are many different ways to name variables. From the hard to understand single-letter variables, through semantically named variables, there is a lot to consider.

The most important thing here is once again consistency. Work with your team to identify a standard which everyone is happy to follow. Don’t let this be a single person’s decision. It doesn’t matter how good your standards and style guides are if everyone hates following them.

Choose a casing style and stick to it. Don’t go around mixing snake_case and camelCase. It will be confusing and hard to follow in the long run. If most of your code has snake_case variables, and then just one variable is declared in camelCase, you might spend an undue amount of time trying to understand why this variable is unique, when at the end of the day there is no reason aside from inconsistency.

Architecture

Consistent architecture is a vital part of building quality into your solution. As mentioned above, the key benefit of being consistent is having things work pretty much how you would expect. It makes systems safe to depend on, and it makes it easier to make educated guesses about how the system works. Being able to make these educated guesses about how parts of the project will come together is crucial.

If you look at one part of the system and come to understand it, you might assume that other analogous parts of the system would follow the same rules. If you delve into these other systems only to discover that they are inconsistent, that is no good at all.

Consistent architecture is the sort of thing that needs to be planned. If you try to free-style it, you will likely end up with an inconsistent amalgamation of different patterns which don’t necessarily blend. To avoid this unfortunate state, you should have a pretty good idea what sort of application architecture you are going to go with before you start writing code. In this instance, it also doesn’t hurt to record architectural decisions using something like the aptly named Architectural Decision Records (ADR). This acts as a sort of documentation for the architecture and can help explain to others further down the line why particular decisions were made, what alternatives were considered, and other useful fragments of information like this.

Consistency leads to predictability, reliability, and ultimately quality. If you care about quality code, consistency in everything you do should be your first port of call.