Reading Code is a Skill

I'm inspired to write this post because Someone Is Wrong On The Internet. Of course a more accurate statement would be "I disagree with some aspects of what someone on the internet said, even though they have an entirely valid point of view". But that's less catchy.

I saw a Tweet I agreed vehemently with, so I retweeted it:

I can't say this enough.

You will read code more than you write code.

Learn to get good at it.

— Laurie (@laurieontech) August 31, 2020

A number of replies to my retweet said variations on this theme:

I'd rather say, learn to write READABLE code !

— Devesh Mankar (@Devz15) August 31, 2020

Yes, and, possibly even more importantly:

Learn to write code that is easy to read. (Yes, easy-to-read code is often harder to write. Do it anyway.)

— Brian Goetz (@BrianGoetz) August 31, 2020

(Note: I have the greatest respect for Brian Goetz, and I don't disagree with the sentiments expressed in any of the Tweets embedded in this post. But I do feel very strongly that there is more to the story. Read on...)

The problem is not that we shouldn't write readable code. Of course we should aim to write readable code, if only for our own poor selves further down the line (there is no one less capable of reading my code the following week than me). The problem is that these two issues are not mutually exclusive. It's not "write readable code" or "learn to read code". That's like saying, "I'm going to drive really economically so I don't need to put petrol in the car". No. You're still going to need to put fuel in the car (if it's not electric!) at some point no matter how economically you drive.

Similarly, no matter how much you try to write code that's readable, and no matter how hard everyone else around you tries to do the same, the reality of life is you will have to read code that you find difficult to understand at some point in your career. Like, probably today.

Let's look at the problems with the approach of "just write readable code".

1. It's wrong to assume someone wrote unreadable code

Yea, I agree to the point of being able to read under the hood open source code of an API used in your app, or you need to take handover from other dev, but getting handover of an UNCLEAN code for further development should be discouraged.

— Devesh Mankar (@Devz15) August 31, 2020

It's just plain wrong to assume "unreadable code" was the output of someone smashing away at the keyboard and not caring about one of the consumers of the code, i.e. other programmers. Code that's hard to understand is often a result of an accumulation of things:

• The code was written at a time when the language/framework didn't do then what it does now;
• The code was written a while back and the fashions and "best practices" back then were different;
• Each line of code was written with readability in mind, but over time as more lines got added, the overall message was lost;
• People moved on and moved away, and now you haven't got anyone to ask about the business or technical reasons behind something (and of course the documentation is horribly out of date).

...etc etc. No one writes unreadable code on purpose. You can see this for yourself if you have a project that only you contribute code to - every time you come back to it after an absence of months, weeks, or even days, you wonder what on Earth you were thinking when you wrote it, because now you know a much better way of doing the same thing, or you have a name which is much clearer for this method.

That's just not reality for large enterprise applications. It's not a case of "handover" or "unclean", it's a case of a large, mature, codebase written by many people with evolving technologies, styles and fashions. That's the reality many live in.

— Trisha Gee (@trisha_gee) August 31, 2020

2. It's a narrative of blame and it doesn't solve anything

The narrative of "unreadable code is the fault of the code author, you should be writing readable code" focuses on placing blame rather than looking at how to deal with the issue. It's easy to blame the author for writing something bad, and to make a pledge to only write readable code ourselves. It's much harder to put aside our ego and think "right, the skill I need now is the skill of learning this new dialect in the code and deciphering what the intent was". Yes, it's fun to feel good about ourselves by grumbling about the quality of the code we've inherited, but it's not getting us anywhere.

Imagine if Baz Luhrmann thought "that Shakespeare guy couldn't spell, and iambic pentameter makes it really hard to understand his plays. I don't think I'll bother getting to grips with Romeo & Juliet, Shakespeare should have written it better". We would have missed out on a unique film just because the original story isn't "readable" by today's standards.

And also learn how to be kind and caring to the reader

— DiegoEH (@DiegoDeRosario)

Yes, we should write readable code to be considerate of the reader (who might be future-us). We should also be kind and caring to the authors of the code, and learn to accept the code as it is. A true professional learns the dialect(s) of their code base. A true professional has empathy for the contributors to the code. This will help them to better understand why things are the way they are, and only then can they figure out the best way to move forward.

3. Readable code is subjective

I can't assume that what I think is readable is something you can understand immediately. My idea of readability, like a code base's un-readability, is an accumulation of my experiences. I've worked at a bunch of different places using a bunch of frameworks and patterns. If I'm dumped into an unfamiliar (Java) code base that uses any of these, I'll have a decent idea straight away what's going on. But stick me in a modern JavaScript application and I will likely be lost - I can read and understand code line-by-line but my ability to grasp common patterns or the bigger picture will be much more limited than an experienced developer. Of course useful method and variable names, short methods, an intentional design and so on should make it easier to understand. But it doesn't magically overcome my lack of familiarity with a particular language, framework, pattern or business domain.

By all means, make the reader's job as simple as you can, but you can't assume that just because you wrote code that you think is clean and readable that all developers will be able to understand it.

Reading code is a skill

Which brings me to the final, and also original, point. Reading code is a skill. Reading code is a skill that can be learnt, and can be improved. Time, experience, practice, with different languages, frameworks and libraries; different code bases; different programming styles; different patterns, will improve your ability to read code. I couldn't read Spanish eight years ago, now I can follow most written content. Reading Spanish turns out to be something that gets easier with practice (who knew?). It's the same with code. Of course, we read code all the time, whether it's in our code base or StackOverflow, or blogs or books or whatever, so that's a great start - we will get better at reading code simply by doing our job. But it's not enough. Kathy Sierra talks about "deliberate practice" in Making Users Awesome. We get significantly better with deliberate practice than through simple exposure.

Reading code is a skill that we can improve with practice. Next time we see code that we don't understand, we shouldn't beat up the author for "not writing readable code". We shouldn't beat ourselves up for being stupid for not understanding it, because we all come with our own unique experiences. We can instead see it as an opportunity to practice reading this particular code, and leveling up our "reading code" skill.

In Summary

• Reading code is a skill.
• Encouraging developers to "write readable code" does not take away the need for developers to level up their "reading code" skill.
• And of course you should write readable code.

I have a whole talk on this topic, which I guess is how strongly I feel about it. On that page you'll also find a bunch of links to other useful talks and articles.

Update: 3 December 2024

I still feel so strongly about this topic that I created a video about it. I also include some IntelliJ IDEA tips to help you get better at understanding code.