Here’s a simple way to improve communication among the programmers in your community: stop calling code “unreadable” and when you hear someone call code “unreadable”, ask them what kind of “unreadable” they mean.

What’s Wrong?

I’ve noticed at least two different meanings of “unreadable” over the years:

• complicated
• unfamiliar

Not only are these meanings different, but they can lead you towards mutually-conflicting strategies. If you assumed that they mean “complicated” when they mean “unfamiliar”, then you could easily propose a strategy that makes the situation worse, not better.

Please explain this conflict!

The problem lies with the use of abstraction. It’s the reason some people (incorrectly, in my opinion) whine about frameworks.

We make complicated code simpler by first removing anything obviously irrelevant. Sometimes we write code that could merely be deleted in the cold light of day. Programming is stressful and so it’s surprisingly easy not to notice that you’ve written 10 lines that do nothing or didn’t see how to apply De Morgan’s law to make a boolean expression simpler. Let’s suppose that we’ve already removed all that cruft.

Next, we make complicated code simpler by hiding distracting details and leaving exposed only the details that a client needs to use the code safely, accurately, and with confidence. We call this strategy abstraction: hiding the repetitive details of a pattern so that we can focus on the distinguishing details that make this implementation different from another. An abstraction seems helpful if it hides only the details we don’t care about and unhelpful if it hides too little or too much.

Humans understand abstraction only through exposure and repetition. They tend to prefer to generalize from concrete examples, so most programmers understand abstraction best by refactoring (at least once in their life) to cause the abstraction to emerge.

This means that the solution to complicated code makes the stress of unfamiliar code feel worse. Simplifying code encourages us to introduce abstractions, whereas making code more familiar encourages us to inline abstractions.

I see this often when a technical leader wants to introduce some helpful library to make the code more concise, but the rest of the project community complains that they don’t understand what that library is doing. The unsuspecting programmer calls the resulting code “unreadable” (really, unfamiliar) while the technical leader considers the code “more readable” (really, simpler). They could—and sometimes do!—fight for weeks. Worse, the technical leader often considers it their responsibility to “drag the rest of the group into the 21st century” while someone among the “unwashed masses” takes on the responsibility of “leading the resistance to tyranny”.

No, really. It gets ugly surprisingly quickly.

What Could We Do?

I propose two complementary strategies:

• Don’t call code “unreadable” (or “readable”, for that matter)
• When someone else calls code “unreadable”, ask them which kind of “unreadable” they mean

If someone has trouble articulating the kind of “unreadable” they mean, then offer them some possibilities: complicated? unfamiliar? merely “not the way I’d have written it”? Don’t worry; we’re on the same side here. I merely want to understand you so that I can propose something more likely to actually help.

But I can’t stop myself!

I know. Don’t worry. When you notice yourself calling code “unreadable”, remind yourself not to stop there. Take a breath, then describe what you don’t like about the code. Ramble, if you have to. Some people need to start talking for a while before they understand what they’re trying to say. Some people need to think about it, and if that’s you, then ask for time to think about it. “I don’t like this. I’m not sure why yet. Give me a few minutes.”

When you remember how easy it is to impulsively call code “unreadable”, you might find it easier to treat other people with more compassion when they do it. “OK. I get you. Take a moment. When you say ‘unreadable’, in what way?” If you like Clean Language, then try asking a Clean Question, such as “What kind of ‘readable’ is your ‘readable’?”

Like many of these tricks, it becomes easier with repetition. Give yourself and each other the chance to practise.

We Need Help!

Try playing “What’s Not To Like About This Code?” in order to practise articulating more precisely why you find code “unreadable”. It provides many benefits beyond addressing this specific problem. You can start by trying it once for about an hour and following the rules the best you can. If you would prefer using this game in the presence of a skilled facilitator, I can help. It’s not free, but you might find it valuable.

The Theory

Here are a few models and concepts that lie behind the idea in this article:

• The “Interpretation” part of the Satir Interaction Model (“Ingredients of an Interaction”), The Law of Three Interpretations, The Law of Generous Interpretation, Nonviolent Communication’s “Giraffe Ears”.
• Abstraction means “hide details”. Not all abstractions are helpful. We can become more comfortable with abstractions (and abstracting!) by using The Simple Design Dynamo.
• The speaker and the listener in an interaction share responsibility for the quality of communication; therefore, I recommend strategies for both acting differently as a speaker and acting different as a listener. The Responsibility Virus and “The Responsibility Process”.
• There are very few examples of “unreadable” code: this ignores the perspective of the reader and the fact that people experience what they read differently! Even very complicated code can become familiar enough to some programmers that they read it with relative ease. Some of you might even have been The Person Who Actually Understands This Stuff.

One More Thing…

When someone refers to code as “more readable”, you can safely substitute in your mind something such as this:

I believe that more people will understand this code more confidently and less expensively as measured in effort or stress.

Doing this deftly replaces a so-called objective statement that you might have the impulse to refute with a subjective statement that you might reasonably challenge, explore, or otherwise let pass for the time being. Many people find it easier to let people “be unusual” than “be wrong” and maybe you’re one of those people.