Programmer Musings

Review of Code Reading

Code Reading
Diomidis Spinellis
Addison-Wesley, 2003

I have had this book on my list of books to read for some time. Although I have been reading code for years, everything I had heard about this book suggested that it would help improve my reading skills. Unfortunately, halfway through the book I was mostly disappointed. This is not to say that the book had not covered loads of useful information, it was just stuff I had already found on my own.

As I progressed through the book, however, I found more and more useful tips and suggestions. Although a few were things I had never seen before, many were techniques I had not used in a while and had forgotten. By the end of the book, I am firmly of the belief that this book is a must-read. Even if you find parts of it to be obvious, there is enough material to extend almost everyone's understanding.

The book starts off with basic techniques, recognizing language constructs and coding idioms. It then moves on to data types and more advanced control flow. Eventually we pass through documentation and architecture, on our way to tools that help your code reading. A few of the pieces of advice are more useful for more junior code readers. Such as, pointing out that

for(i = 0; i < len; i++)

should be read as loop len times. You should be able to recognize this without actually parsing the code. The author also spends time unraveling boolean expressions and showing how changing the whitespace in a complicated expression may make its meaning more obvious.

It also covers more advanced advice like reminding you not to expect a single over-arching architecture in a piece of code. You may spend time trying to find something that is just not there. The book also covers the important trade-offs involved in using documentation attached to the code. There are also wonderful maxims like

An hour of code reading can save you a minute of reading the documentation.

and

Documentation may often provide a misleading view of the source code.

In addition to documentation and the code itself, Spinellis supplies advice on using comments in the code and the change logs under version control to help understand the code. He does not suggest that the comments and change logs should be taken as the truth. However, he does point out that they may help to clarify the purpose or intent of the code.

One of the most fundamental points made by the book is that how you read code depends on what you are trying to do with it. If you are trying to repair or modify a small piece of a large body of code, you don't need to understand the whole thing. I know that I am personally guilty of trying to get deeper into code than is necessary. On the other hand, the book shows examples of needing to dig further when your understanding does not match the program.

The book includes a relatively extensive list of references that might be worth reviewing to extend your knowledge of this field further. The book comes with a CD containing a reasonably large body of open source software that you can use to practice your code reading skills. The exercises in the book are geared toward using that code base.

This book is a must read for any junior or intermediate software developer. If you need to maintain anyone else's code, this book gives lots of strategies to make your work easier. Despite my initial impression, this book provides an good refresher for more senior developers. It does a very good job of reminding you of techniques that you may not have used or may not have used recently.