C/C++ Users Journal August, 2004
Code Reading: The Open Source Perspective
Diomidis Spinellis
Addison-Wesley, 2003
528 pp., $49.99
ISBN 0201799405
The first mention of Diomidis Spinellis' Code Reading I saw claimed that it would revolutionize the teaching of programming. After reading it, my response is, "only in the hands of a good teacher."
In the hands of someone trying to impose the One True Way on the next generation, it will be a tool of oppression. This is a backhanded compliment; it is a poor tool indeed that can't be abused. Code Reading is full of good tools with something new for almost everyone. You'd almost think that, in an article on debugging C++ memory allocation problems, Cameron Laird had Code Reading in mind when he spoke of "'intermediate' tools that leverage experience, without substituting for it" (http://www .informit.com/articles/article.asp?p=102648/).
Code Reading is full of intermediate tools and tips that can substitute for personal experience:
The main reason for this is that a pointer is a low-level, powerful, yet blunt tool. Learn to distinguish its uses and common coding patterns will emerge; view the remaining few instances you cannot classify with suspicion.
Then follows a dozen pages of common patterns. There is an important metaprincipal here that is followed throughout the book—idioms are minipatterns that work in real life. Choosing not to follow them where appropriate is a sign of ignorance, a possible mistake, or a flag to readers, "Here be Dragons," so proceed with caution. The appropriateness of idioms can be culture/ context specific:
The use of alloca is discouraged in some programming environments like FreeBSD because it is considered non-portable and machine- dependent; in other cultures like GNU its use is encouraged because it reduces accidental memory leaks.
Spinellis' central premise is that the way to learn to write good programs is to read good programs. In the same way, we expect people to become good writers by reading the literature. With the advance of open-source software, there is plenty of good software to read, hence the subtitle "The Open Source Perspective." The accompanying CD-ROM has 7 million lines of source code from 16 different projects. Even if you do not intend to work with open source, this book is still valuable.
The examples are predominately in C, but there are examples in C++, Java, Ada, Python, Smalltalk, Perl, troff, and XML. If you know at least two languages—one of them object oriented—there shouldn't be much of a problem understanding the examples. The principles are rarely language specific.
Despite the metaphor of reading code as literature, the primary emphasis is on reading code for a specific purpose. From Appendix E, "Maxims for Reading Code:"
Read code selectively and with a goal in mind. Are you trying to learn new patterns, a coding style, a way to satisfy some requirements?
Spinellis gives strategies on how to drill down to the section(s) you want and avoid reading from front to back. Having located the relevant section, he suggests looking for debugging code (often conditionally compiled or commented out) and assert statements. These often indicate key points: troublesome code or the programmer verifying that the constraints of the code are observed (for example, buffer lengths are nonnegative).
Though there are a few Win32 programs, most of the examples come from UNIX-like systems. GUI programs are in the minority because "reading and reasoning about such programs really deserves a separate book volume."
So who is this book for? Anybody who is or who is about to spend time with someone else's code (that code may be yours from several years ago). As a college course, a senior- or graduate-level seminar is appropriate. For people already in the workplace, organize a reading group. Skill comes with practice, so do the exercises on real code. And try for a mix of experience levels—having already encountered a situation for which one of these techniques is a solution is very helpful.
The worst thing I can think of to do with the "Maxims for Reading Code" is turn them into a bulleted list to be parroted back. A better use is to photocopy them, cut them into strips, and pull one from a hat when you hit a dead end. Or if you use the command line, add them to the fortune program's database.
Code Reading is a book that will age very well. Little of it will be irrelevant in 10 years and most will still be relevant in 20. Sounds like the makings of a classic.