What is Quality Code?

Code quality is a topic of a surprising amount of debate in my experience. Most of that debate has been amongst colleagues about the minutiae of coding standards and whether or not a certain solution is better or worse than an alternative. What’s most surprising though is the debates about whether or not code quality is worth the effort or even if it is important at all.

Before we can address that though, we’ll need to agree on just what quality code is. I’ve heard lots of opinions about it over the years, here’s a few of them.

Quality code works like it should.

I have a lot of problems with this definition, but mostly it’s just that this is the absolute lowest possible bar for judging code. We can do better, can’t we? Also, how code is supposed to work is often a matter of opinion and not well defined in some requirement document.

Quality code is readable and understandable.

This used to be my definition of quality code. I was obsessed with formatting of code. It’s true that any given piece of code is more often read than written, however it’s also more often executed than read. Writing code to be read tends to push a code base towards longer chunks of procedural and imperative statements. These aren’t the best choice for every problem and can lead to code duplication and dependencies in the case of large and complex applications.

Quality code is commented.

Oh yeah, I used to love comments too. Comments often lie though. Comments may mislead and are out of date. You can’t ever really trust comments.

It’s far better to write readable code than to comment it. Give a bit of code a name by encapsulating it in a method (method names can lie too, that’s called a side-effect, but it’s much less likely).

Quality code is protected with automated tests.

This is the working definition that Robert Martin uses in his influential book “Clean Code”. I highly recommend it, however this definition didn’t sit well with me then and it doesn’t now. His argument is that without tests, quality code will decay over time. Tests protect it, document it, and allow safe and confident improvement of the code. Tests are important, but they don’t magically improve the quality of code by themselves. At their worst tests can have all the negative effects of comments.

Still, read the book. There are a ton of great insights into how to achieve clean code.

After years of thought, I’ve arrived at my own definition. It’s rather broad and says nothing at all about what quality code looks like or how it’s achieved. This is a benefit because it allows us to evaluate many styles and techniques for improving code and not be bound rigidly as the industry evolves.

Quality code is code that can be changed, as needed.

First, recognize that all code must change. The needs of stakeholders and users change; the application must change to meet those needs.

As an illustration, imagine a deal with the devil; The devil offers an application that perfectly meets all of your needs. In the fine print, however, is a clause that stipulates that the application may never be changed to do anything other than what it does right now. I suspect there are many who would take that deal, and none that wouldn’t live to regret it.

Secondly, the code must be able to be changed “as needed”. Code that cannot be changed when it needs to be changed is not quality code. Business is competitive. Windows of opportunity are a thing. If your code isn’t flexible enough to change in time to take advantage of your opportunity, it isn’t good enough.

Code that cannot be changed to do what is needed is not quality code. If the stakeholders have to compromise what they want because of the difficulty of changing the code, then that code isn’t good enough.

Written on August 30, 2014