On Reading Code Well

(Full disclaimer: I don’t think I read code well. I think I read code better than I used to, though.)

It’s a truism at this point to say that code is read more often than it is written. Of course code is read more often than it is written (though I would of course welcome any examples of write-only bug-free codebases). This is why, as developers, we are constantly encouraged to write clean, well-documented code that will be readable to others who will come after (even if that other is us, a year from now, and we’ve forgotten everything we held in our head while we wrote said code.)

But something that I’ve noticed- both for myself and for people learning how to program- is that writing code seems to be easier than reading it, for new and experienced programmers alike. It’s an odd thing; unlike most other crafts, for many it’s actually harder to piece together somebody else’s writing than just to write it anew yourself.

I can’t think of many other crafts where this is true (though I really like the idea of hundreds of people on the beach writing their own political thrillers rather than bringing one).

Indeed, I think the comparison to reading a novel or a story is a revealing one. The stark imbalance of writers vs. readers in the world shows us that vastly more people want to read and consume books than write them, and this is true even though the vast majority of people are perfectly capable of writing (Maybe not writing well, but let’s set that aside for now).

But what sort of reading do people actually do? It’s light reading, for the most part: people read novels, or skim them, or use them to pass the time. It’s rare that people truly, actually engage with the text at hand. This is much, much harder: really entering the text, laying it bare, and getting at all the undercurrents, motifs, themes, and hidden subtext is exhausting, slow, painstaking work, and often requires reads, re-reads, and note-taking.

More than that, it requires training: it’s not easy to do this off the bat. Very few people have the ability for deep reading right away. It requires a conscious effort to not skim, to consider words in the context of the broader narrative, to recognize motifs, and more. It requires a reader to have a whole arsenal of explanatory and analytic tools in their toolkit before they can truly say they’ve read a book deeply.

Ask anybody if they’d rather read Moby Dick or write an epic about a whale, and I think most people would take the reading. But ask them to do a deep, painstaking, exhaustive read that gets into the really nitty-gritty parts of explication?

I think more than a few people would start to want to write their own story about a whale.

And this is, in effect, how lots of programmers approach reading code: we don’t really grapple with what we’re reading. When we open a project repository, we’re faced with a daunting prospect: thousands (perhaps even tens or hundreds of thousands) lines of code scattered across dozens of source files. More often than not, we’re under time constraints: there’s a bug in this project that needs to be fixed, and the project maintainer is out, or we’ve stepped in to maintaining this full-time, etc.

So what do we do? Much like our whale-reading friend above, we skim. We look around haphazardly where the code starts: we breeze past nested loops, trust comments and function names (surely get_project_name gets the project name, right?) and kind of give a once-over to tangled bits of conditional logic that seem right. Eventually, we kind of have a dim idea of what’s going wrong, we write a test case, and patch some code until the bug is fixed and the tests pass.

And this is even for well-written code: reading poorly written code can be even worse, and can slow down the process even more. When faced with something that’s really in-depth (like refactoring) that requires us to really read the code, well…

Writing a new story about a whale sounds a whole lot better.

And I think this is because a lot of emphasis is placed on code writing, but not necessarily code reading. Before I set about writing this article, I gave a couple of cursory searches on the subject; outside of a few articles (and an interesting book I think I might have to pick up) there’s not a ton of material on reading code. There is, however, a ton of material on writing code: orders of magnitude more than on reading code, and I think this leads us to having a much broader toolset for writing code than we do for reading code.

Because, much like deep reading above, reading code requires its own set of skills and tools. Learning to write code gives us the bare minimum to read code, and a lot of best practices and methodologies that are useful in writing code are also useful for reading code, in a limited fashion. More than that we glean from repeated practice: we are forced, as developers, to relearn code reading practices through repeated, frustrated attempts at reading other complex code.

I’ve had the good fortune to work with some really good code readers, and I think I’ve gotten much better in the past couple of years. But this is because they took the time (and had the time) to teach me, and show me ways of thinking about code exploration: it’s like being inducted into a Masonic order where the only transmission of knowledge is from master to apprentice, with internal wikis to guide you, which really limits the scalability of the whole enterprise.

Is it any wonder, then, that given the emphasis on writing code and not reading it that developers often choose to re-write existing code rather than read it?

For code readers, we need to start documenting how we do it: best practices, methodologies, ways of looking at and diagramming program flow and source code structure that make it easier and faster for developers, new and old, to break into unfamiliar codebases. We can’t rely on code always being clean, well-written, and documented: Reading code is reading code, not reading the comments around it or the API interface that’s documented for it.

And for developers who struggle with code reading, well… take heart. Keep practicing. It’s exhaustive, frustrating, and painful, but every day you really take the time to read some code is a day you get slightly better at it. Instead of writing a new story about a whale, maybe get familiar with one that already exists.