Tom Lee

Software development geekery.

Coding Standards: Consistency Is King

I just read Richard Rodger’s article “Why I have given up on coding standards“. I loved this:

The truly evil thing about coding standards is what they do to your heart, your team’s heart. They are a little message that you are not good enough. You cannot quite be trusted. Without adult supervision, you’ll mess up.

(Emphasis mine.)

Awesome stuff, and I think Richard’s right in that coding standards are a demoralizing lost cause. However, I felt the conclusion he ultimately came to stopped just short of saying something really important:

I expect everyone to write good clean code. You decide what that means. You decide if you can sleep at night with random code layouts and inconsistent variable names. But you know what, maybe they just don’t matter for a 100 line node.js mini-server that only does one thing. You decide.

(Emphasis mine again.)

I understand the sentiment, and I agree with it in so much as that you need to trust smart people to do smart things. But for all their flaws, coding standards are often introduced to address a legitimate problem: it’s a pain in the arse to read code that is formatted inconsistently. Code bases that are inconsistent* are generally harder to understand.

So how do we maintain consistency given that we’ve established that formalized coding standards suck?

Write your code such that it’s consistent with the style of the code around it.

For example:

In the file you’re editing, are curly braces on the same line as a function declaration?
Put your curly braces on the same line, too.

Whitespace before brackets?
Put spaces before your brackets.

Tabs instead of spaces?
You use tabs too, even if you object to tabs on principle.

Seeing a pattern here?

You improve the consistency of your code base (a major goal of coding standards!) by trying to be consistent. It’s not rocket science.

The part where you need to trust developers to be “smart” comes along when there are obvious inconsistencies in the code:

Well, this source file uses a mix of tabs & spaces. That sucks. I’m going update the file to use spaces because that’s what we use in the rest of the project.

Now, even after reading Richard’s article (and this one) you might be thinking “but without rules, code will never be perfectly consistent!”. You’re absolutely right. But odds are folks were fucking up trying to follow whatever coding convention you put in place anyway.

Formalized coding standards aside, making an active effort to be consistent will generally lead to code that’s easier to follow.

Of course, you could always save yourself the trouble and start writing everything in Go. :)

  • All of this is true of architectural decisions too. If you’re going to make a better architectural “wheel”, you’d better be prepared to update the existing wheels. Otherwise, I’d wager 9 times out of 10 you’re actually making things worse… but maybe that’s a post for another day!