On Coding Consistency

As software projects grow larger, some aspects gain importance while others lose. In fact, most of what you read and learn about software engineering is really only applicable once your project reaches a certain scale threshold.

Of course there are small, niche problems where software correctness is paramount (such as mission-critical software), but for most information systems (database-backed systems) that are at least large enough for complexity-related issues to become noticeable, a serious candidate for the one most important metric is probably its ease to change and extend.

For most information systems, ease to change and extend may well be the most important metric in the long run.

A lot has been written, said and discussed about ways to keep complexity under control and grow software in ways to prevent it from becoming too complex to deal with. There are a number of ways to help maintain your code easy to change and extend, e.g. writing modular code, keeping coupling low, using well-know design patterns, etc, but today we will discuss consistency.

Consistency means simply always doing the same thing in the same way.

Software is primarily an intellectual, abstract artifact. You can't see it, you can't touch it and you can only talk about it in indirect terms.

For this reason, when we first look at code written by others, we need to make a mental model of what that code is meant to do. If your code is consistent throughout your project(s), it's much easier for others to figure out what it should do, find bugs, and extend it. This also helps lighten the cognitive load people face when studying your code.

In times of social coding and public github repos, you want as many people as possible to quickly understand your code to be able to extend it and help your project grow. If any code you write ever becomes popular and widely used, its consistency (or lack thereof) will be put under test constantly.

To put it another way, if your code isn't consistent, it just won't be used as much and will probably have a short lifetime in the wild.

Here are some examples of ways in which you can start enhancing consistency in your projects:

• Naming things consistently - in other words, things should have one, and only one, name throughout your project. This goes for actual code, variable names, comments, interface definitions, and so on. Different names for the same thing make it very difficult to understand what your code is supposed to do.

• Consistency in code style - Pick one and stick to it! Although there is considerable debate over what coding style one should use, in large projects it really doesn't matter which you use, as long as you keep using the same style throughout the project!

• Consistency going about problems - The way you design a method or a class should also be consistent. For example, if you have separate methods to fetch a Database handler, another to query and so on, make sure you follow this script on everything you do; after 2 or 3 classes, whoever is reading your code will expect all classes to follow this pattern.

• Consistency ordering and organizing things - Much like an indexed database, our brain works much better when things are in their expected place. If things are consistently listed in alphabetical order our brain comes to expect things to be in that order and it's one less thing to worry about. Ruby on Rails' Convention over Configuration is a prime example of this. Having developers agree on an informal standard makes development easier, especially when teams grow large.