Blog

Every so often an article crops up with some big list of rules to follow to keep your code readable – It’s something everyone seems to want, but it is also accompanied by a bloodbath in the comments from people who disagree on how to do it.

As a coding beginner, you eventually realise that you do need to make your code readable – people who write the clear, readable code are the ones that get hired, and the ones other developers like working with.

Rather than pass down a big list of rules that you must follow or else, I have attempted to distill advice about readable code into a series of guidelines and rules-of-thumb for you to follow, and steadily build on as you grow.

Why should we make code readable?

A major reason we try to make code readable is to reduce cognitive load – that is to say how much focus we need to maintain to work with it.

Contrary to what you might experience when you’re learning to write code, most of the time when working in the industry is spent reading code – It is often much harder than simply writing it yourself (code you wrote a month ago is effectively written by someone else).

For developers, focus is one of the base currencies we deal with (aside from time, caffeine, and money), so being able to keep your code nice and readable is paramount to a code base you enjoy working on.

Keep it simple

A core tenet of readable code is to keep your code simple – Fair warning though, this is far easier said than done. It requires understanding the nuances of the problem, and being able to craft a concise solution that deals with all the edge cases. This kind of solution usually comes with experience with the problem – The best thing to do is to write a shitty solution first, and while it’s still fresh in your mind, try and simplify it.

Tell people what you’re doing

A core tenet of reading anything is whether we understand what is going on. The simplest way of making sure people understand what is going on is to simply tell them. In code, this comes in two forms: Comments, and the code itself.

Consider the following code example (and I admit it’s a little contrived):

function m(a) {
	return a >= 0 ? a << 2 : -(a << 2);
}

This function looks damned complex. It must be doing something important. Here is what it does:

1. Return the absolute value of a * 4

I bet you didn’t guess that.

Now that we know what this function does, it’s actually really simple – But why does it look so complex? Answer: it doesn’t give us any hints as to what it’s even trying to do.

1. function s gives us very little to go on. We could use absMultiplyBy4 – You could strip it to multiplyBy4 but that would cause confusion when we start getting absolute values back
2. a tells us nothing. Only by knowing what the function is supposed to do can we tell that it’s supposed to be a number. Since this is a mathematical equation, it’s hard to provide something exceptionally meaningful, but we can at least hint at the type of variable we expect – num or val would be much better.
3. Our intention is to multiply by 4. Using a * 4 over a << 2 is much clearer, and falls back on elementary arithmetic instead of obscure binary arithmetic.
4. We’re returning the absolute value in a strange way. num >= 0 ? num : -numis a completely correct way to return an absolute number, but there is the standard library Math.abs to do it for us, and it’s far more descriptive.

function absMultiplyBy4(num) {
	return Math.abs(num * 4);
} 

This is far more obvious.