Adam O'Grady

Coding Standards

TL;DR:

Readability, followed by consistency.

The Eternal Arguments

These are just a few of the positions at the centre of ideological arguments in developer communities that run the gamut of friendly banter to vitriolic ALL CAPS flamewars. Each side has it’s merits and can present solid arguments for it’s use. But all these debates do is cloud the actually important factors behind coding standards.

Readability

First and foremost, code should be readable by anyone who may have to maintain it. As the adage goes, you should always code as if the next person who will work on it might be a murderer with an axe to grind. Some good examples of this are using whitespacing in languages where that isn’t as important.

for(i=0;i<20;i++)console.log("hello world");console.log("fin");

Just because you can write like the above, doesn’t mean you should. Check out a better way of formatting this below:

for(i = 0; i < 20; i++) {
  console.log("hello world");
}
console.log("fin");

Notice how we become more liberal with the use of spaces and include braces around the looped statement. While it’s not necessary, it instantly removes uncertainty about what code is being looped over.

And just because you can write code so it looks like another language, doesn’t mean you should. If you’re coding in Java, make it look like Java even if you really like Python syntax or it may end up like:

Java coded like python

This becomes a mess and requires a huge amount of concentration to sort through. With a long enough time and familiarity it would be possible to grok this code but why burden someone with that when more pragmatic and simple coding styles exist?

Consistency

The second major thought behind coding standards is enforcing consistency. This helps and is part of readability as anyone looking at your code who knows the basic styling rules can more quickly absorb the intent and get to work on it. In the end, it doesn’t matter if you choose to indent with tabs or spaces, use camel or snake case for variables and something else for functions - as long as you adhere to that style.

Beyond simple syntactic style, you also need to consider things like function parameter order (needle, haystack or haystack, needle), programming paradigm (functional/procedural/object-oriented), etc. By creating some ground rules about all of this, it reduces confusion when using that code elsewhere, maintaining it, or adding new features.

Consider using a linter/formatter in your CI pipeline or as a pre-/post-commit task to help enforce style and remove potential compatibility bugs and undefined behaviours.

Flexibility

Despite all that I’ve said so far, a key thing to remember is that these rules shouldn’t be enforced dogmatically if they would interfere with changes.

If function arguments make more sense to be reversed in one occasion, do so. If you’re importing a third party library that uses different case, you don’t need to write an entire interface so it fits your coding style. Knowing when and where to make concessions is an important skill.

Hey you didn’t say which was best?

Folks, it doesn’t matter. All that’s important is the above commandments. Readability, consistency, with a dash of flexibility as required.