Is Readability Truly a Code Quality

November 29, 2016 — Posted by Max Guernsey

Readability and code quality frequently coincide but does that mean readability is a code quality?

My friends and colleagues 

This is an important distinction because quality problems in code demand changes to that code.  Smells, on the other hand, merely require investigation.

A lot of bad code is effectively impossible to read, except possibly by its original author.  Is that enough to make readability a code quality or its lack thereof a pathology?often refer to readability as a code quality.  I’m beginning to question that position.  I think that unreadability is a smell, rather than readability being a code quality.

It might not be.  To me, code qualities are intrinsic to the code of which they are qualities; they are inherent.  Readability has a subjective component that, in my mind, excludes it from the category of a “code quality”.

In fact, the subjective nature of readability sometimes runs counter to the interest of code quality.  For example, sometimes someone says something is unreadable simply because they don’t understand how to read it.

Why Does this Matter?

Code qualities have teeth.  Claiming a design has a lack of code quality in a persuasive way is likely to cause that design to change, for better or worse.

Code smells lack that social power.  The “investigate and understand” directive attached to any pungent odor in a codebase is far more likely to lead to an open conversation that results in the correct change – which isn’t always to the code, itself.

If the degree of readability is moved into the category of a code smell, I believe the conversations around unreadable code will produce positive results more frequently.

The Unreadability Monster

We’ve all seen it.  That chimeric miscreation.  It’s impossible to comprehend and may even baffle creator.  The design is impossible to navigate, the algorithms it contains are inscrutable, and the symbols might even be technical gibberish.

If you haven’t run into that yet, I can think of two reasons:

1.       It’s a utopian future in which bad code no longer exists.  Congratulations!

2.       You’re just starting your career circa the time of this writing.  Brace yourself.

In these kinds of cases, the code in question is both low in quality and poor in readability.  It’s easy to see how one might start to develop an association between readability and quality from such data points.

The Readability Boon

There’s another class of data points that reinforce the idea that readability is a code quality: code that is highly-readable to a reasonably-well-informed professional also tends to be high in quality.

The act of considering the readability of a design often helps someone improve that design in a more fundamental way.

For instance, picking a good name for a class superficially improves the maintainability of a system by making it easier for future developers to learn that class’s job; that part is obvious.  What is not obvious to everyone is that finding a good name for a class ensures that it is a class that can have a good name.  This implies things like cohesion, encapsulation, and an intention-oriented interface.

Thus, we see another cluster of designs with good readability and high quality.  Again, I can see how this reinforces the idea that readability is a code quality.

Two Points, but Not Necessarily a Line

We’ve got two clusters of data which are prominent in our minds.  At least, they are prominent in my mind; I tend to think “Remember that terrible design?” or “Remember that wonderful design?”

Each cluster has a very strong correlation with the level of readability.  The terrible design is usually something nobody could read or understand, with the occasional exception of the original author(s).  The wonderful design is usually something that was easier to learn and recall.

Yet, as most of us know, correlation does not imply causation.

What is A Code Quality?

Now it’s time to switch gears a little.

Part of answering title question is clarifying the boundary between code quality and other attributes.

It seems obvious to me that code quality must be intrinsic – part of the nature of the code being measured.  A code quality is, after all, a quality of some code.

For example, a class is exactly as cohesive as it is.  The level of cohesion in a class is totally independent of an observer.  Two classes are either coupled or they aren’t, regardless of whether I can see it when reading some code – in fact, regardless of whether or not there even is someone making observations at all.

I think that, to be a true code quality, something should hold to that standard: it should be an innate property of the code completely independent of any influence from observers.

A Twist in the Line

Readability is extrinsic, not intrinsic.  The observer matters a lot.

In fact, despite appearances, code doesn’t have a level of readability.  Code is readable or unreadable to someone.

For instance, code could be perfectly well designed and completely readable but, if all the names are in Chinese, I wouldn’t be able to make head nor tail of it.  That wouldn’t make the code unreadable.  It wouldn’t make the code low in quality.  It just means that someone who can’t read Chinese can’t read that code.  Yet the code might be perfectly easy to understand by even someone who speaks broken Chinese as a second language.

The Twist Becomes a Wrinkle

It doesn’t take anything as drastic as the previous example, either.

Slight differences between readers’ knowledge of design can create a disagreement about how readable a block of code is.  In fact, the exact same observer might regard the readability of the same block of code very differently after a short conversation with another developer.

I’ve had that happen several times.  Smart people for whom I have a great deal of respect start out thinking code is unreadable and grow to understand over the course of months, weeks, days, or even minutes.

The fact that readability exists outside of code and, instead, lives in the relationship between a reader and a block of code means that readability is not a code quality.  At least, to me it does.

Code Smells Versus Code Qualities

Let’s look at another kind of observation we can make about code: code smells.

There are numerous well-known code smells: a long method and a long class are two pretty smelly examples.

Code smells are inherently subjective.  To illustrate this: What does “long” mean in “long method”?  My nostrils start to twitch at around three or four lines, most of the time… maybe ten under very special circumstances.

I’m on one extreme of the “how long is long?” spectrum.  The subjective element is even more apparent when you watch someone work with some legacy code to which they’ve grown accustomed; they often exhibit the “I’ve been in the barn too long to smell it” effect.

Code smells are known to indicate or suggest rather than diagnose problems.  So, while low code quality mandates a refactor to eradicate something you know is a problem, a pungent code smell only suggests investigation.

Readability Seems More Like a Smell than a Quality

I think readability aligns far better with a code smell than a code quality.

A lack of readability suggests that investigation is required and that something probably needs to change.

However, poor readability doesn’t tell you what might need changing.  Maybe the design of the code in question needs to change.  Then again, maybe the understanding of one or more team-members needs to be updated.  …or maybe both.

Subscribe to our blog Net Objectives Thoughts Blog

Share this:

About the author | Max Guernsey

Max Guernsey, III is a Senior Consultant at Net Objectives


Blog Authors

Al Shalloway
Business, Operations, Process, Sales, Agile Design and Patterns, Personal Development, Agile, Lean, SAFe, Kanban, Kanban Method, Scrum, Scrumban, XP
Cory Foy
Change Management, Innovation Games, Team Agility, Transitioning to Agile
Guy Beaver
Business and Strategy Development, Executive Management, Management, Operations, DevOps, Planning/Estimation, Change Management, Lean Implementation, Transitioning to Agile, Lean-Agile, Lean, SAFe, Kanban, Scrum
Israel Gat
Business and Strategy Development, DevOps, Lean Implementation, Agile, Lean, Kanban, Scrum
Jim Trott
Business and Strategy Development, Analysis and Design Methods, Change Management, Knowledge Management, Lean Implementation, Team Agility, Transitioning to Agile, Workflow, Technical Writing, Certifications, Coaching, Mentoring, Online Training, Professional Development, Agile, Lean-Agile, SAFe, Kanban
Ken Pugh
Agile Design and Patterns, Software Design, Design Patterns, C++, C#, Java, Technical Writing, TDD, ATDD, Certifications, Coaching, Mentoring, Professional Development, Agile, Lean-Agile, Lean, SAFe, Kanban, Kanban Method, Scrum, Scrumban, XP
Marc Danziger
Business and Strategy Development, Change Management, Team Agility, Online Communities, Promotional Initiatives, Sales and Marketing Collateral
Max Guernsey
Analysis and Design Methods, Planning/Estimation, Database Agility, Design Patterns, TDD, TDD Databases, ATDD, Lean-Agile, Scrum
Scott Bain
Analysis and Design Methods, Agile Design and Patterns, Software Design, Design Patterns, Technical Writing, TDD, Coaching, Mentoring, Online Training, Professional Development, Agile
Steve Thomas
Business and Strategy Development, Change Management, Lean Implementation, Team Agility, Transitioning to Agile
Tom Grant
Business and Strategy Development, Executive Management, Management, DevOps, Analyst, Analysis and Design Methods, Planning/Estimation, Innovation Games, Lean Implementation, Agile, Lean-Agile, Lean, Kanban