There have been a lot of articles and books written about readability (I know, I wrote the chapter in Clean Code about naming). Many studies are written about how code structure and code quality affect readability.

I think it’s time to update our understanding of code readability, and maybe help forge a path forward from here.

What Is Readability, And Why Do We Care?

Every working program is readable to some degree.

If the source code runs, it is at least readable by the parser.

A careful reader who spends enough time carefully reading it will eventually understand it.

How long does it take to:

• correctly understand what the code does?
• recognize side effects and failure modes?
• decide whether the code needs to change?

We say ‘readable’ as a shorthand for “easy to quickly and correctly understand” relative to other ways of expressing the idea in code.

I referred to readability as ‘clarity’ in the Code Virtues article, which you may want to visit now before reading onward.

We improve code clarity to save developer time.

Since misunderstanding the code can lead to errors, we improve code clarity to reduce the chance that a future maintainer will introduce defects in that body of code.

Clarity is important because it makes it possible to write better software, sooner.

What makes code clear?

Developers will move quickly when they are familiar with the language, framework, libraries, and idioms used.

Lacking such familiarity, they must slow down to carefully study the code.

They may have to look up definitions of the words or meanings of unfamiliar punctuation.

They may need to read background articles to fill in missing knowledge.

This significant difference must be considered:

Clarity is mostly a matter of familiarity.

I don’t find Norwegian signage very readable, but Norwegian people find it very clear and easy to read. Why? Because I don’t know Norwegian, and they do.

People come from different schools and companies and therefore are familiar with different styles.

We mistake this as “simple preference” and “subjective style” and sometimes assume it is an untenable situation, but most of us shift our coding style when working with different languages or as we gather experience.

Style is not permanent.

There is an uncomfortable thought here: years ago, when we taught people to use a more “readable style”, we did that by introducing the audience to the style that we felt was more readable to us as an audience.

Instead of making the code more readable, did we make the audience more familiar with our shared style?

Would the results have been the same regardless of what style we taught?

“I Write Clear Code!”

We used to think that readability is an attribute of each source code artifact (such as a file, function, or module) we created.

We missed an important truth:

Clarity is a feature of the relationship between an artifact and its audience.

When the audience declares that a passage of code is not clear, it doesn’t matter what the author thinks; they have failed to reach the audience.

As a writer, I understand that the onus is on me to write in a way that others can clearly understand without misunderstandings. The audience is usually in a hurry, and I can’t sit back and blame their level of literacy. I need to accommodate my audience if I want to get my message across.

There’s a corollary here:

The way to determine if the code is clear is to have the audience read it.

If familiarity is the bigger part of clarity, then we have to write code that the audience finds familiar even if it is not the form that is unfamiliar to us personally.

Catering to the audience this way includes their choice of formatting as well as naming and idioms

I think we nearly understood this when we were talking about egoless coding and the importance of writing code that our peers can understand.

There is also leverage here: if this is a two-factor consideration, then we can either change the artifact or change the audience.

Improving the relationship of the code to the team can be done by changing the way the code expresses ideas, or by changing the team’s appreciation of the code, or (typically) both.

As the audience acquires new ways of expressing code ideas, those new expressions become familiar. Being familiar makes them “clear” or “readable” to the team.

As new people come to the team, they will also acquire these ways of expressing code ideas and may also bring additional new idioms to the team.

“How Can I Write Code My Team Approves?”

The best way to write code that your team can use is to co-create it with your team so that you all are reading it as you all are writing it.

This way you can weigh in on clarity, duplication, functionality, and all the other virtues that are important to you.

Ensemble Programming (AKA Teaming) also allows the team to become familiar with language features and frameworks together, so that when some new technique is encountered in a body of code – perhaps in an emergency – it is already familiar to everyone involved.

If one does not co-create code with teammates, then one is pretty much stuck with a trial-and-error situation where one person writes code and the rest of the team rejects it until somehow the author happens upon an expression that the team likes or else the team decides to accept code that they don’t easily understand (a “normalization of deviance”).

It seems safer, smarter, and faster to co-create code, but that doesn’t mean people can’t possibly make it work any other way… eventually.

“Readability Isn’t Everything”

This is true. Clarity is not even the #1 virtue in the ordered list of code virtues.

There are other virtues other than clarity, and I invite you to consider writing code that is Working, Unique, Simple, Easy, Developed, and Concise as well.

Focusing on only one virtue to the exclusion of the others is not prudent, so please focus on them in the appropriate order and to the appropriate measure.

If, in fact, code clarity helps to produce better software sooner and more sustainably then it is unwise to ignore it.

Why not start by reviewing and refactoring code in groups and see what happens when you pay more attention to the relationship between the code artifacts and the code’s audience, your team?