Read The Code

I've been thinking a bit about code reading lately. When code reading usually comes up in a discussion, it is usually about how to document the code and how much comments to add.

But I'm thinking about the skill of pure code reading - the ability to read raw source code and figure out how it works. 

Up until recently, I wasn't really aware of its importance. To be more exact, I assumed everyone's code reading skill more or less followed the overall amount of programming experience. 

It turns out it's not quite like that. Instead I've come to understand that code reading is a skill quite separate from the "general programming" skill.

I talked to one colleague about reading code, and he told me his way through complex code was not to rush headlong into the code and read it until he understood it (my preferred method), but instead he would look to divide and refactor the code into separate pieces with clear interfaces until each piece could be understood on its own.

While I think that this is a good approach to clear up complex code, it will still be hard to do the best possible refactorings unless you really understand the inner workings of the code you trying to clean.

This brings to mind a story that was related to me by another of my colleagues:

This colleague had been hired as a consultant to finish some software project. Working his way through the code he was struck by how strange the programmer who originally worked on the project had designed the program.

Believing the previous programmer had simply made some design mistakes, he went ahead and threw away the weird parts of the code and started to rewrite them. 

His newly written code started out pretty clean, but as he began work on the details he noticed the need for amendments to his original design.

As he implemented more of the details and corrected his design to accomodate them, he began to realize that his design grew more and more to resemble the original "strange" design he had thrown out.

I think this illustrates how hard it is to know what parts of the code are needlessly complex and can be safely thrown away, and what parts are complex because the code is handling some very complex details.

I suspect that good code reading skills always will be an edge, and in some cases even an essential skill.

So what can we do to get better?

There are a few ways I know of that will teach code reading: 

• When reading a programming example, always try to run the whole programming code in your head to figure out what it does - never use code you don't understand.
• Fix bugs in other people's code.
• Translate code from one language into another.

I haven't read it myself, but I suspect Diomidis Spinellis's Code Reading also has some good ideas, and Joel Spolsky has an interesting blog entry that suggested a form "pair-reading" to get through truly complex code.

But most important is, as always, the desire to improve.