How Do You Evaluate Code Readability?

Evaluating code readability is actually pretty easy.? I’ll explain it in a way that you can easily illustrate with a flow diagram.? And you can see if you agree with my assessment.

1. Did someone else write this code?? If so, it’s not readable.
2. Did I write this code but more than six months ago?? If so, it’s not readable.
3. Otherwise, it’s readable.

Sound about right?

I kid, but only kind of.? This tends to be my visceral, subconscious reaction before I reign myself in and think rationally.? And I bet the same is true for a lot of you reading as well.

Code Readability and Subjectivity: the Elephant in the Room

This happens because of the inherent subjectivity involved with the idea of code readability—or, more specifically, with the idea of readability in general.

To understand what I mean, let’s use an extreme to make a point.? I could write a few lines of C# that just about any programmer reading would understand at a glance.? But a non-programmer or neophyte programmer might read it and fail to grasp even these basics.

“What does ‘return’ mean?”

So readability depends on your prior knowledge and your perspective.? And frankly, it also depends a lot on your own preferences.? Some folks seem to like compact, dense code while others favor frequent empty lines to “space things out.”

What does all of this add up to?? Well, it means that we cannot possibly tackle this subject without acknowledging the opinion-based and subjective nature of it.? But that doesn’t mean we shouldn’t address it.

A Loose Framework for Discussing Code Readability

I’m going to spend the rest of the post offering my opinion on how you can make your code more readable.? But before I do that, let’s reframe slightly.? Let’s think of code readability as time to comprehend.

Of course, time to comprehend doesn’t eliminate subjectivity.? But it does introduce a measurable concern that we can use as a metric.? So, for the rest of this post, I’ll talk about code readability in terms of time to comprehend, with the following guidelines:

1. We’re talking about time to comprehend for a developer in the language of average experience.
2. Matters of preference and familiarity will affect this time to an extent, but so will various language properties.
3. Code readability is generally preferable, but not in all cases (e.g., you might have need to optimize a critical path where advanced language usage and other concerns trump readability).

Now, all of this is still my opinion about code readability.? You’ll have your own opinions, of course.? But it’s through this lens I offer you the following tips on how you might evaluate and improve code readability.

Use Descriptive Names for Code Elements

First up is a suggestion you’ll see pretty commonly for code readability.? Use descriptive member names to make it clear, at a glance, what’s happening.

As a rule of thumb, you should also use more descriptive names for larger scopes.? For instance, naming a loop counter variable “i” is fine when the scope of the loop is a single line.? But don’t name some class field or method parameter “i” if you want people to understand its meaning.

When you abbreviate things or give them inscrutable names, the time to comprehend goes up.? The people reading your code have to stop to puzzle out name meanings or else go look them up somewhere.

Keep Classes and Methods/Functions Small

Like the machines we program, we have a limited, high-performance cache when it comes to our memory.? Popular psychology theorizes that we can keep track of seven plus or minus two things in our heads as short-term memory.

When you have a method or class that keeps things relatively minimal, readers of that method can grok it pretty quickly.? But when you start pushing the cognitive limit, they’ll struggle.

What does pushing the limit entail?? Here are the sorts of things that you file away as you process a method:

• Parameters and their meanings
• Local variables and their meanings
• The return value
• The instructions in the method

When those things start pushing our capacity, time to comprehend goes up sharply.? Instead of holistically understanding the method at a glance, you start to trace paths through it with your finger, add temporary comments as notes to yourself, or even get out pen and paper.? That slows things down considerably.

Create Meaningful Abstractions

This one might seem a little surprising.? When talking about code readability, most people talk about consistent indentation standards and such.? And those things do slightly impact time to comprehend, but they more create a sort of aesthetic friction in our reading of code.? They?annoy?us the way that this stack of Fig Newtons annoys us, but they don’t necessarily torpedo comprehension.

A pattern of haphazard abstractions does, though.? This includes leaky abstractions, failed abstractions, and misleading abstractions.

How does this impact code readability?? Well, when you have poor abstractions, you have to dig into them to understand.? So when you’re invoking a method in a codebase or instantiating a class, you wind up not understanding what it does or not believing it when it says it does something.

This general pattern of suspicion violates the principle of least astonishment?and ratchets up comprehension time.? Write code that does what it says it will, and that hides complexity.

Be Idiomatic

There’s often a fine line to walk when writing code and thinking about readability.? I alluded to this a little earlier in the post, when I talked about a target audience of the “average” developer.? If you cater to a novice, you might wind up with a lot of extra code or awkward code where a more intermediate or advanced language feature could have made things easier.? But if you really lay on the language usage, you might confuse even experienced developers.

Admittedly, this is a tough (and subjective) line to walk.? But you’d do well to walk it by being idiomatic in your language.? This means using common conventions that people writing in that language use (e.g., Pascal vs camel case) but also using things like using common design patterns or approaches.

The short version of this is that you can make your code readable by making it resemble code that people in your stack commonly write.? This reduces time to comprehend via familiarity.

Don’t Use Comments as a Crutch

Code comments is a topic I’ve tackled a number of times on this blog.? I have a nuanced opinion on them, and I may court a little controversy here.? But so be it.

This post is about code readability, which I evaluate by time to comprehend.? Code comments don’t help with code readability—they help with comment readability.

This might seem like semantic nitpicking, but it’s an important distinction.? Comments in code (not method header documentation, but explanatory comments) generally occur when the author thinks maintainers will struggle to comprehend the code.? They don’t make the code more readable—they attempt to prevent you from needing to arrive at understanding by reading the code, the same way that you sitting there next to the maintainer explaining the code would.

So if you want to make your code itself more readable—reduce its time to comprehension—don’t rely on natural language to do the job for you.? Focus on figuring out how to make the code clearer, whenever possible.

How Do You Evaluate Code Readability?

These are some of the ways that I strive to improve my code readability, and I encourage you to consider them for your own code.? Thematically, the goal is to make it so that maintenance programmers (you or others) have to spend less time understanding your code.

How do you evaluate code readability, and what do you suggest to improve it?? Feel free to weigh in below in the comments with both tips and overarching philosophical approaches.

Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.

About the author

Erik Dietrich

Website

I am Erik Dietrich, founder of DaedTech LLC, programmer, architect, IT management consultant, author, and technologist.

This author does not have any more posts.