Readability is paramount

November 10, 2021

I grew up, as a software developer, in the world of Perl. Perl’s motto is There’s more than one way to do it, (abbreviated to TIMTOWTDI and pronounced: Tim Toady).

As the thinking goes, this flexibility allows the programmer to write more concise statements, as well as choose a style that fits the context, or their whims.

But is this a good idea?

I distinctly remember the day I was trying to explain some Perl code to a colleague. The beautiful one-liner ellegantly iterated a list through a map function, and utilized the a subtle side effect to trigger an update to a variable, which was later read for its state.

After stepping him through everything it did, and him still shaking his head, I re-wrote it into a 3-line form that anyone could understand.

I’ve come a long way since then.

I once felt that writing short, clever code was the proof of my superior coding ability.

But what value is short, clever code that nobody understands?

People are usually the most expensive part of any IT system, so we should optimize for people’s time.

This means writing readable code, rather than clever code.

This usually means writing readable code rather than efficient code.

The same principle applies, of course, to non-code artifacts as well. Config files, diagrams, documentation. Optimize for readability.

Readability should usually be the first priority in any technical artifact you write. Of course there are exceptions, and I’ll talk about some of those in the coming days.

It’s harder to read code than to write it.
— Joel Spolsky

Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.
— Robert C. Martin

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
— Martin Fowler

Related Content

Your code looks like Chinese to me!

Perl, Java, C++ are as hard for novices to read as a randomly designed langauge.

Readability vs performance

Are there times when performance is more important than readability? Yes. Should that be your starting point? Absolutely not!

When is a shortcut appropriate?

The only time less typing is more important than readability is on the command line. When writing code, readability wins by a mile.