Legibility over Efficiency in Code

I’ve been coding for about six years now, and I’m the first to admit that I have much to learn. I actively code in about five languages at the moment, mostly web technologies, and code on the web is more legible than most. It’s shared, remixed, made open source, distributed as libraries and well documented. But it’s horribly inefficient. And I think that’s okay.

The Need for Speed

In many applications, efficient code is seen as critical, at least by those who write it. And it makes sense – physics engines or graphics rendering engines need to be able to process all calculations fast enough not to slow down the program as a whole. I can understand why military or space flight applications need to be efficient when lives are on the line. Businesses, like those doing micro-trading a block away from the New York Stock Exchange, can gain a competitive advantage with highly optimized code.

And the stakes don’t have to be that high, either. Companies want their websites to load quickly on a mobile phone. App makers want their apps to be responsive and appear to the user as instantaneous. And as a consumer, I get impatient with anything resembling a loading screen. So why not define ‘well written code’ to be ‘the most efficient code’?

“Efficient” Code is a Falsehood

When we speak about efficient code, what we’re really talking about is code that completes its calculations faster than some arbitrary alternative. But that rabbit hole can go extremely deep, because by that measure, code can almost always be made more efficient. Fewer lines of code, condensed operations, minified code, and on and on right down to binary optimizations.

But the paradox is that each level of optimization makes the code less efficient, because it’s humans that have to write, read, edit, test, debug and verify that code. The more we gain in raw performance, the more we lose in legibility and understanding.

I’ve only been coding for six years, so a lot of code can be difficult for me to parse, at least quickly. Ask me to debug a program, and the code efficiencies are the parts I’ll trip over and take more time with, possibly even introducing new bugs. And I’m just as bad, writing code that I can’t hand off to someone who’s only been coding for a few years and expecting them to understand my single line ternary operator functions or null aware operators without having to mentally unpack it and translate it in their heads to a code pattern they’re more used to working with.

If we’re going to write ‘efficient’ code, we need that code to be understandable by anyone who ever needs to read it – from beginner to expert – so we don’t waste their time. Efficient code needs to be about the humans, not the computers. It may result in more keystrokes for an advanced programmer, but humans can’t think as fast as we can type anyway.

There are exceptions, of course. The efficiency gained overall by making a BIOS or something run at peak performance is an obvious benefit. But for the vast majority of code written every day, we need to start writing it for humans.

Proposal: An Eighth Grade Reading Level for Code

The most popular pieces of fiction and non-fiction are written at a level where schoolchildren can understand it. A masterpiece of literature or a newspaper article rarely requires a full high school education. Just because you have a PhD doesn’t mean your writing should be readable only at a PhD level – in fact, you’d be doing a service by simplifying it for the rest of us. (You can read a great analysis of reading and writing levels here).

I propose the same standards for code.

Code should be readable by the average eighth grader. And there’s no reason it can’t be. When I encounter a complex (and more than often obtuse) piece of code, I translate it in my head into an equivalent I can understand. But there’s nothing stopping the original author of that code writing code simply to begin with. The code may not run at peak performance, but the humans working with that code will.

Strive to make your code legible, for yourself and for those that are going to read your code later. You’ll save everyone time, allow for more people to comprehend your code, and ultimately the net human result of all of that code you’ve written will be a more efficient world.

Header photograph by Christiaan Colen, licensed under Creative Commons.

Leave a Reply

Your email address will not be published. Required fields are marked *