Reading Code is Like Reading the Talmud

Seth Gordon emailed me some great tips for reading other people's source code:

I started working as a technical writer in Boston after about eight months studying at an Israeli yeshiva.

A year or so ago, I and a co-worker were trying to decipher a yacc-and-Perl monstrosity that generated some of our documentation. We sat down with printouts of the code and went through it, virtually line by line. "Now, because of the way yacc works, when it encounters *this* kind of data, it will run *this* function ... what does *this* line do? ... at *this* point, what does that messy data structure look like?..."

Another co-worker asked me how it was going, and I told him, "It's just like reading Talmud."

The following Talmud-reading tactics are, I think, also useful for code-reading:

1. Work in pairs, thinking out loud to one another.
2. Argue. If your partner says "this means X", and you either don't understand why or you have another opinion, demand an explanation.
3. Sometimes, when dealing with a chunk of text, it's easier to figure out the middle *after* you understand what's on both ends. Therefore, if a fragment of text has you stumped, try skipping over it and seeing if you can come back to it later. (But you still have to come back to it eventually.)
4. Read the text both "inside" and "outside". An inside reading translates the text into English (or whatever your native language is) phrase-by-phrase; an outside reading translates a larger chunk into an idiomatic paragraph. If you only read inside, you can miss the forest for the trees; if you only read outside, you can fool yourself by making broad guesses and not verifying them with details.

My new book is here! Apress has just published a new collection of 36 essays from Joel on Software, aptly named More Joel on Software. Get yours today! Available from Amazon.com or wherever fine cheese is sold.

About the Author: I’m your host, Joel Spolsky, a software developer in New York City. Since 2000, I've been writing about software development, management, business, and the Internet on this site. For my day job, I run Fog Creek Software, makers of FogBugz—the smart bug tracking software with the stupid name, and Fog Creek Copilot—the easiest way to provide remote tech support over the Internet, with nothing to install or configure.

Enter your email address to receive a (very occasional) email whenever I write a major new article. You can unsubscribe at any time, of course.