Code readability - is it useful?
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 (i'll 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 approval yourself. 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 a huge 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!
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 will then become the goal, and
the team will optimize for those rather than readability itself.
How to get readable code then?
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, 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.
11/1/22
I'm happy to announce that Alexia
Mandeville and I have formed a new game company named Bodeville!
Bodeville is the realization of our dream of making games with complete creative freedom. I firmly believe that
the only way to get this freedom is by not taking anyone else's money. Too many times in the game industry, people
have been promised creative control only to have it taken away when the executives or investors decide otherwise.
By self-funding, we are beholden to nobody but ourselves (for better or worse!)
Without a big pile of cash, we are starting small. The two of us will try to make an entire game and manage the
business at the same time. We'll cut as many corners as we can without sacrificing the vision and the experience.
The games will be smaller in scope than those from a 10 or 100 person studio, but we hope the story and soul will
still shine through.
We will post development updates on Bodeville's website
and twitter page. My personal takes
on games and business will be here. I look forward to sharing the experience with you!
10/18/22
I hear a lot of conversation about quitting these days. "Quiet quitting" is all the rage.
A former poker player has written a new book on quitting. And it's something that's been
on my mind since I quit my job nearly six months ago.
I'll focus on why I quit rather than cover the multitude of reasons that others quit.
And the reason is quite simple - because I wasn't happy!
On the surface it seems like an idealistic, irrational decision - quitting because of one's feelings.
The money was good, and in theory working in game development was fun. Our depression-era
ancestors surely would disapprove of leaving a good-paying job.
But how do you measure mental exhaustion, burnout? And how to value the ability to be present
and energized for my family and friends after the day is done?
This is where I think the line between rational and irrational behavior in our society is misplaced.
It seems that anything subjective or immeasurable is by definition irrational. It reminds
me of economic theory, in which we are taught all about "rational consumers" who are always perfectly
maximizing their utility. These models can't possibly place a value on the range of human emotions.
So yeah, I quit because I was unhappy. It's kind of like relationships! Of course, you want to try your
best to make it work out, and give it a fair shot. But once you realize that things won't turn around,
it may be time to go.