Lately, I’ve been reading books on programming style and techniques. The most recent addition is “Software Exorcism: A Handbook for Debugging and Optimizing Legacy Code” by Bill Blunden. I have not found a tremendous amount of new material in the book, but there are a few interesting examples. It’s the author’s voice however that is of relevance in this case.

I’ve had the privilege to work on four books, three of which were separate titles. My positive opinion of writing for O’Reilly is entirely due to the gifted editors assigned to work with me. During both “LDAP System Administration” and “Using Samba”, they drilled into me the need to be concise in my wording. They put my prose on a diet. I can honestly say that at the time the books were published, they were the best work I could produce.

The problem I have with Blunden’s book is the use of personal speaking style when writing. It becomes a distraction to me and borders on pretentious at times. Technical topics should be covered with a rational, Spock-like approach. Because this seems counter intuitive to anyone that has had to do any public speaking, most first time writers fall into the trap of translating those oratory experiences onto paper. I did myself in my first book. I believe that the tendency to “wax poetic” is an attempt to over-compensate for our own fear of inadequacy, that someone will question our right to teach others or will know more than us.

As software developers, we spend a create deal of time designing and writing new code and then an equal amount of debugging that code (or possibly someone else’s code). Modern compiles include a variety of options to help optimize good code and eliminate bad code.[1] Removing defects like the use of uninitialized variables and unreachable code should be pursued with deterministic precision. Of course, there is still room for personal creativity. Whether you use “for (;;)” or “while(1)” in C, the end result is the same.

Eric Raymond once told me he believed that most good developers possessed ability to be good writers. I am by no means an ESR fan, but I think on this point he is correct. The reason is that the same drive that forces us to consider all the possible ways to write an algorithm and then choose the most efficient and elegant one can also be applied to the technical explanations we write in our native language. In prose, as in code, content is king.

[1] I have a love-hate relationship with gcc’s -Werror.

(Originally published 5/8/2009 on www.plainjoe.org)