What Does Code Quality Actually Mean?

Written by Erik Dietrich

I hear people toss around the term "code quality" a lot. Of course, I'm sure you do as well. It's hard to spend more than a few days in a software shop without hearing someone say this word. But here's the rub. It never seems like anyone means exactly the same thing when they talk about it.

Think of food, for instance. If I tell you that I went out last night for a high-quality meal, you'd probably map your own definition onto my experience. Maybe you picture high prices, kale, and homegrown pine nuts. Too light? Maybe a rib eye with fingerling potatoes that's also expensive. But, either way, clearly expensive and organic. What's that? Maybe to you, a high-quality meal is a cheap deli sandwich and who cares where it's sourced? Of course, if you were lost in the woods for a week, you might redefine high-quality food as literally anything edible.

You probably get the idea. The way you regard food is subjective and also context dependent. And the same holds true with the way we regard code. When we talk about code quality, we bring our own context and subjectivity along for the ride. But, as with food, we also tend to assume people share our definitions, even when they probably don't. This thanks to a human cognitive bias known as naive realism.

So how do you go about unpacking the idea of code quality, achieving at least some consensus?

Code Quality: Definition by Negation

Perhaps the easiest way to get started involves coming from the negative side. After all, if we learn anything from Software Engineering Stack Exchange, we learn that the question of what constitutes code quality will inspire hundreds of votes, lots of answers, and many comments before being closed as "not constructive." But we also learn that people can agree on (and up-vote) a definition of what it's not.

People everywhere seem to agree that poor quality code inspires disbelief in the beholder. They read the code and feel inspired to exclaim loudly, "what is this?!" Code of poor quality perplexes or stymies us, as immortalized in a semi-famous cartoon.

I actually think this serves as a pretty good starting point for the discussion. When you have code of poor quality, it confuses people and defies comprehension. So, flipping it around would seem to make a good starting point for discussing code of good quality -- people should understand it quickly and easily.

Of course, you might point out that any code would confuse someone with no or rudimentary knowledge of software. So perhaps we should think in terms of code easily comprehended by the average software developer familiar with the technologies in question.

The Code Does What It Should

We can thus establish some heuristic table stakes from negation before moving onto narrowing the field with straightforward criteria. To have high-quality code, the average developer should be able to understand it quickly and easily.

Notice that this creates a situation where one could have incredibly clever or even groundbreaking code not qualify as high quality. And, on the whole, I'd say that's okay. If you crank out some incomprehensible algorithm that solves a unique, profitable problem, you can probably stand the ego hit of a heuristic guide to code quality not giving you the highest marks. And, what's more, your contribution is less a function of the quality of this code and more a function of what it does.

And that brings up another important property of code quality. It should, as table stakes for high quality, serve its intended purpose. This means that high-quality code doesn't have bugs, performance issues, security holes, or other things that render it unfit for purpose. You can have sloppy code that serves its purpose (even quite well, as in the case of a revolutionary solution to a problem), and you can have understandable code riddled with bugs. Neither of these represents high-quality code. But understandable code that does what it's supposed to keeps you in the game.

Reads Like Clear Prose

With some table stakes in place, the definition comes to a higher bar. Let's say that you've written code that conforms to the principle of least astonishment, and that it does what it's supposed to without issue. Now you've got something that doesn't generate defects or make people exclaim in disgust. That's good, but it seems like we can do better.

Proponents of clean code offer a series of aphorisms on the subject. These include the idea that it comes without surprises, does what you expect, and looks as though the person who wrote about it cares about it. But I find that Grady Booch summarizes it perhaps most clearly.

Clean code is simple and direct. Clean code reads like well-written prose.

That tells you something rather powerful about consensus on high-quality code (and clean code). Programming languages tend to have syntax that makes full use of punctuation most non-programmers never touch. And from there, they have semantics that push the limits of the arcane. Programming languages give you all sorts of opportunities to crank out gobbledygook.

So high-quality code, in a sense, undoes that. It takes all of that punctuation and language feature semantics and presents it to maintainers in a way that "reads like well-written prose." There's an elegance to that, and it speaks of high quality.

Good Code Quality Has a Fundamental Business Meaning

Up to this point, I've offered a series of heuristics that set the table for my own personal take on the matter. I do believe that there's an essential component to what it means to write high-quality code. But, as I've said earlier, the subjective nature of this does make it just my opinion. So, buyer beware.

I've built on consensus here to say that high-quality code doesn't confuse and confound, that it does what it sets out to do, and that it clearly communicates its meaning to maintainers. Like those I've cited and quoted, I believe these things.

But I perceive a general heading that unites them. High-quality code is code that enables the business by holding total cost of ownership to a minimum. That's why fast understanding, correctness, and clarity are so important. High-quality code doesn't force monetary waste on the excessive difficulty of change, constant troubleshooting, and endless rework and rewrites. Instead, it serves its purpose in a minimalist way.

I doubt that we'll ever achieve consensus on what makes code high quality. I might even find myself disappointed if we did, in all honesty. But, consensus or not, I submit that you look beyond your own perception when thinking of code quality and consider what impact the code has on the business that paid for it.