"Readability" is subjective

January 27, 2022
Ask yourself: Will the least experienced developer likely to read this code be able to understand it?

I’ve talked about the importance of code readability before, and so has one of my podcast guests. But “readability” is pretty subjective.

Quick. What does this mean?

/(cat|dog)s?/

If you understand regular expressions, this should be pretty readable.

If you don’t understand regular expressions, you’ll be at a loss.

So is the code “readable” enough? Obviously it depends. Do you expect the readers of your code to understand simple regular expressoins?

So here’s my rule of thumb to determine if code I write is “readable enough”:

Will the least experienced developer likely to read this code be able to understand it?

When developing a simple web service, I usually assume that the least experienced developer to see the code may be an intern, or a recent coding bootcamp graduate. So I strive for “very readable” code.

However, if I’m writing some deployment scripts for Kubernetes, it’s far less likely that a 3-month bootcamp grad will be tweaking those files. I’m willing to be “a little less readable” if it makes the job easier for me.

Or maybe you’re hacking a kernel module to improve the performance of some network filtering. Most likely, the types of developers reading that level of kernel code have many years of experience, and you don’t need to focus on child-like readability very much at all there.

The bottom line: “readable” is subjective, so keep context in mind when writing your code to be readable.

Share this

Related Content

Go Code Roast #2: readability.js port

In this video, I roast a port of a Mozilla Javascript library, [readability.js](https://github.com/mozilla/readability) to Go.

Go Code Roast

In this video, I roast some Go code! That is, I review it as if it were submitted as part of a job application screening. I talk about what I like, what I don't like, and how I would do things differently.

When is a pull request too big?

Smaller pull requests are faster to write and easier to review. Here are 4 tests to see if your PR might be too big.