What Does Code Quality Really Mean?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look around and check out Collaborator, the code review tool.

Let’s say that you wanted a definitive explanation, once and for all, as to what constitutes code quality.  You might take to google and type “definition of code quality,” which would yield a post from this very blog as well as a sampling of Q&A sites.  For the purposes of this post, however, I’d like to examine the entry that occurs here, at programmers’ stack exchange.  I think it may be the perfect microcosm for this discussion.

The Q&A Site Consensus

The question is simple enough: “what does it mean to write good code?”  The answer receiving the most votes is one in which the respondent draws a parallel to top-notch pool players, who are so good that they set up their next shot as an easy one, even while making the current shot. High-quality code “looks like it was easy and straightforward to do.”  This is a classic example of “I can’t define it, but I know it when I see it.”  You can recognize code quality because it “looks easy.”

Next up in vote total was a response that cited a popular, somewhat crass cartoon.  The gist of it is that code quality is inversely proportional to the number of perturbed utterances per minute on the part of people reading the code.  High quality code is code that triggers this response infrequently, whereas low quality code triggers this response vehemently and regularly.  Like the answer preceding it, this is not a definition but a recognition heuristic.  But with this response, the respondent clarifies that such a definition may actually be impossible, and heuristics are the best approximation.

From there, the answers get more specific and acquire fewer votes each.  One respondent offers “how fast can you understand the code” as the defining criteria for high quality code.  It is easy to imagine push-back by someone pointing out that “while(true) { }” is trivial to understand, but the resultant application that simply hangs is probably not the product of high quality code.  For the most part, the rest of the answers list properties of good code in an attempt to provide the requested definition.  “Good code is bug-free, reusable, well-documented, easy to change, etc.”  None of these garnered many votes, but each did receive a few.

So what was the verdict?  There was no accepted answer and the moderators closed the question as “not constructive.”  The reason cited was, “this question will likely solicit debate, arguments, polling, or extended discussion,” thus rendering the question not a fit for Stack Exchange’s paradigm of being a Q&A site with discrete and concrete answers.  This is not an indictment of the question, per se, but rather a determination that it’s inherently subjective.

Code Quality as Subjective

What does good quality mean?  That’s a subjective question in any domain.  What is good quality music?  What counts as high quality food?  What is high quality code?

Likewise, across any domain, you’ll hear heuristic answers that make minimally controversial claims so as not to be wrong.  Good quality music is music that makes people happy to hear.  High quality food is food that that I buy a lot.  Code quality means that the code is easy to understand.  Disagreement with these things is going to be rare, but at the cost of predictive value and specificity.  Maybe Mozart doesn’t make me happy.  Maybe I buy a lot of Twinkies.  Maybe I’ve practiced so much that I have an easier time understanding code without whitespace.  All of these things put me at odds with popular sentiment about quality, but, according to the heuristic triangulation approach, they just contribute to defining quality.

Let’s say you move to more objective criteria.  Good quality music follows melodic patterns.  High quality food is nutritious.  Code quality means that it’s nice and spaced out, rendering it readable.  The problem is, I no longer agree with these definitions.  I like discord and I don’t like Mozart.  Twinkies aren’t nutritious, but they’re good.  Take your spaced, readable code and minify it if you want me to like it.

There’s a phenomenon at play here that reminds me of Heisenberg’s Uncertainty Principle.  When it comes to assessing quality in a domain, I can have precision, or I can have agreement, but I cannot have both at the same time.  To get wider buy-in, I need to be vague to the point of platitudes.  To get specific, concrete criteria, I need to accept that many people will not agree with me.

Code Quality Relativity

Does this mean that defining code quality is a lost cause?  I would argue not by asking you to indulge me in a thought exercise.  Since I’ve already added a physics theme to the post, perhaps I’ll think of this as code quality relativity.

Maybe the best way to chase precision with code quality is to abandon the idea that there is an objective definition at all.  On the surface, this seems obvious since different stakeholders want different things out of a piece of software.  Users will say the code is of good quality if the software serves their purposes.  Product owners and project managers will say the code is of good quality if it’s done under budget or ahead of schedule.  Maintenance programmers will say the sort of things mentioned on the Q&A sites: easy to modify, easy to understand, etc.

But this idea of code quality relativity goes deeper than different types of stakeholders and is applicable to, say, maintenance programmers in different groups.  Perhaps it’s okay to say that there is no universal definition of code quality — no universal frame of reference.  Perhaps code quality depends on your group and, more specifically, the operating consensus that it has.  Maybe code quality only has meaning at the group/team level.

Imagine a universe where some omnipotent entity froze all software teams in amber; no one could come or go.  I believe that what you would see is that each team, however much dissension might initially exist, would come to an equilibrium with a common, shared definition of code quality.  And further, I believe that these definitions would gradually diverge over the course of time without anyone being overly concerned.

Of course, we don’t live in that universe.  We like to aim for universal definitions of code quality because we know that teams are relatively ephemeral, and we want our world to make sense wherever we go.  We don’t want to have to re-learn the definition of good code each time the team is re-constituted.  But not wanting to doesn’t mean that we don’t, at least to some degree.

I’m not arguing that we stop worrying about outside opinions or keeping up — far from it.  But what I am saying is that not all definitions of code quality should matter equally to you.  Like it or not, code quality is a relative, subjective concern.  The answer to the question, “what does code quality mean” is “you and your team are going to have to hash that out for yourselves.”