Easier to Read, Harder to Misread
This article is an explanation of my pinned tweet:
This has provoked a wide range of responses and it’s time to clarify.
Firstly, I have used a good dose of poetic licence, because creating a symmetry in the tweet gives it more impact.
Making your code easier to read is usually a good thing to do. Making your code harder to misread is usually an even better thing.
Aren’t they the same thing?
In some cases, yes.
In other cases, no.
Very short code tends to be easy to read, but can also be easy to misread.
The costs associated with a developer misunderstanding how a piece of code works can be and often are an order of magnitude higher than the cost of the developer needing to spend a few more seconds reading a few more lines to correctly understand the code.
Being easy to read, and being hard to misread, are two concepts that are related, but distinct.
I used to think important work and urgent work were the same thing. Learning their differences is one of the most powerful tools for effectively managing work.
“I have two kinds of problems: the urgent and the important. The urgent are not important, and the important are never urgent.” — Dwight D. Eisenhower
Making the distinction between hard to read code, and easy to misread code, can yield similar benefits.
Now let’s look at each of these categories:
Easy to read and misread
The code is terse but potentially ambiguous.
Take a short regular expression as an example. Some people would say regular expressions are hard to read. They are certainly hard to read correctly, but they are also easy to read incorrectly, especially if the developer is not using a specialist tool.
A short regular expression can be read easily, but it might be misread.
Hard to read and easy to misread
This is your regular dirty code. It might contain poorly named variables or classes, or have very long methods. This code is in need of significant refactoring.
Easy to read and hard to misread
This is the clean code that we should always be aiming for.
Hard to read and misread
By far the rarest of all of these categories. This is lengthy and verbose code and has been written so clearly that it is hard to misread. Only one or two tweaks away from being easy to read. An extremely rare sight.
Reducing the risk by making code harder to misread
There are many ways to reduce the risk of misreading code.
If we take the regular expression example, we can rewrite the code so that it does not use a regular expression. This sacrifices the terseness that regular expressions have, resulting in something a lot more verbose, and in that sense harder to read.
But if you write clean code you will have something much more expressive and harder to misread.
Another way is to fully unit test the regular expression. Fortunately regular expressions are very easy to unit test.
You will find that even simple regular expressions need lots of unit tests to fully describe them and all of their edge cases. This process exposes the hidden complexities of the code to both the author and to other developers.
Summary
There are many benefits in writing succinct code. In general, less code is better than more code. However, we should be careful not to get seduced by any notion that beautiful minimal code is the most critical thing.
If the code is too clever, then other developers may be at risk of misreading it. Sometimes it is worth writing some additional code to make the intent clearer to other developers.
Further Reading
Code Examples
I will update this post with more examples as I find good ones.
Example 1 — Octals in JavaScript:
Easy to read and easy to misread: 012
The shortest way to represent this value. However, some people will misread this as the decimal value 12, instead of the decimal value 10.
Easy to read and hard to misread: parseInt(12, 8)
Special Thanks
Randy Skopecek, Matthieu Brun, Attila Buturla, Andy Clarke, George White, Pavneet Singh Saund, Gregor Suttie, Ronald Harmsen, Christos Matskas, Wayne Ellery, Luther Baker.
