The Ups and Downs of Code Readability

For a time at Google, I was a “readability reviewer” for Java code. — that is, one of a group of java experts that had a high standard for code quality. This group had the ability to bestow “readability” powers upon other developers.

Readability (ill use capital-R) was important because all code that was to be submitted needed to be approved by somebody with Readability for that given language. If you had Readability, you could self-approve your code. Otherwise you’d need to find someone who had Readability to approve your code. This was in addition to the traditional Owners approval.

Although two approvals were required, it didn’t turn out to be much of a burden — typically you’d get readability within a few months of joining (or maybe a year for new-grads), and it was more than likely that most people in the Owners file had readability for the language.

I mention Readability just to show how much importance Google placed on readability. On the other end of the code quality spectrum there are people who put minimal effort into documentation, saying that “code is self-documenting” and the docs will get stale anyway and then be a drag. When you do code reviews for this group, it can take a while to figure out what’s going on, and often there’s more feedback than there would be on code from a Readability devotee.

What is readable code, anyway?

At Google and Niantic I was firmly in the pro-readability camp, although I never cared for the extra bureaucracy of an official Readability program. The Readability program, while well intentioned, was a bureaucratic obstacle with a spotty track record.

One person told me that since so much bad code was in the Google codebase, there was an “existence proof” that the Readability program did not work. What was important was a team culture of readability coming from the leaders of the team.

Before I get too far, let me define readability. In my opinion, the readability of code is ultimately how long it takes for somebody to understand how the codebase works and to be confident making changes.

Note that I didn’t mention documentation. While documentation is important, I don’t believe that more is always better. It’s a means to an end rather than the end itself.

My definition of readability is intentionally practical. When you start on a new project, your first task is going to be learning the codebase and fixing a bug. How long does that take? A week? A month? Or maybe you never entirely understand it, you just make a change in the right area and see if it did what you expected.

The missing metrics of readability

When measured this way, readability (lowercase-r) has an obvious effect on a team’s productivity. But how do you know how readable your code is? What metrics are there?

The disappointing answer is, there are almost no metrics measuring readability. It’s an art more than a science. You have to put yourself into the mind of a new engineer and try to imagine where they’d get tripped up and what would help. If the leader of another team had ever challenged me to prove that our codebase was more readable than theirs, there’s no way I would have been able to!

The benefits are almost impossible to see. Perhaps a bug fix will take 30 minutes instead of 60 minutes because the engineer assigned to it was able to grasp the problem quickly. Or maybe a new feature will take 3 days instead of 7 because the existed code was structured well. But you’d have no way to measure that unless a parallel universe of unreadable code existed. Only the intuition and experience of the team can put a value on reliability.

It’s not hard to imagine then why readability could be cast aside in a highly data-driven tech world. One could try and create proxy metrics like “lines of documentation” or “interface to class ratio.” But those metrics will quickly become the goal itself, and the team will optimize for those rather than readability itself.

How to manage for readability

It’s important that the engineering manager instills a culture of code quality and readability. Given that there will be varying opinions on your team about how much code quality matters, it’s important that the manager communicates and enforce standards. If the manager neglects this job and it’s left to the team to decide, this will create enmity as the individual contributors (ICs) duke it out amongst themselves about how important is code quality is, what is the purpose of documentation, etc etc. These arguments have a tendency to reach “holy war” status quickly.

Things are much easier on the ICs when the manager sets the guidelines for code quality. The ICs may grumble about the manager between themselves, but that’s better than the alternative.

Code quality at a two-person company

The irony of everything I’ve written so far is that in my current role as as co-founder of Bodeville, I’m writing the least readable code of my career. I always complain to my partner than I’m having to refactor the code because it’s a mess and it won’t support the next thing I want to do.

Still, I believe I’m writing at the correct quality for the situation. Why?

First, I’m the only person who is likely to ever read this code. Compare that with Google, where you might have 10, 50, or even hundreds of people read your code. The cost of low quality code increases with the number of people reading it. It takes more time to write quality code; if more people are reading it, the higher cost of writing high quality code can be worth it.

Second, the game we are making is a ship-and-release product, not a service. That means the lifespan of the codebase will be considerably shorter than say, Pokémon GO, where the code I wrote as early as 2014 is still being seen every day by developers.

In the game we’re developing, Chief Emoji Officer, I’ve had to do a more than a few refactors and code-cleanups because of the low quality code. I’d be totally embarrassed if the code leaked out. The Google Readability team would think they’d made a huge mistake in letting me join the team. But the cost-benefit of a one-person engineering team actually skews towards less readable code because it lets you develop faster. As the number of people working with your code increases, so does the importance of readability.

Your code could be new again!

A few times in my career, I’ve had to work with code I wrote years before. It had been long enough where I’d completely forgotten the codebase and it was like learning it new. When I wrote the code I never imagined it’d be my future self getting up to speed! But when I found myself in that situation and came across beautifully readable code, it was the ultimate validation of the investment I had made.

But ultimately, your code standards should depend on the product. For a longer lasting product with a large team, the code should be highly readable, well tested, and well documented. On a project with just one developer, you may be wasting time making your code perfectly readable.