Code Complete: Chapter 31

I’ve recently picked up my copy of Code Complete – 2nd Edition again after a long hiatus from it.  It’s such a massive book that I think if you plan on reading it from front to back, it’ll bore you to death and put you to sleep.  Of course, this is not to say that the book is bad – quite the opposite, the book is filled to the brim with knowledge that will benefit any level of developer – but that you have to approach it in a more “leisurely” manner.

The book itself is one of those that you can really just kind of jump in and out of the chapters (except for some of the early ones that should be digested together).

Some bits from Chapter 31 that I think really capture the essence of the book.

McConnell opens with an excellent statement that succintly summarizes my infatuation with proper code structure, naming, and other seemingly “non-development” coding activities: it is a matter of personal pride in my work and the effort that I put forth to make the code legible:

“The visual and intellectual enjoyment of well-formatted code is a pleasure that few nonprogrammers can appreciate.  But programmers who take pride in their work derive great artistic satisfaction from polishing the visual structure of their code.” (P.729)

The chapter covers the importance of good formatting and layout, the psychological effects of good layout and formatting (such as easier to memorize code structure), and techniques to achieve good layout.

McConnell introduces the idea of “The Fundamental Theorem of Formatting” which says “good visual layout shows the logical structure of a program” (P.732)

He quotes Elliot Soloway and Kate Ehrlich in their studies:

“…there is a psychological basis for writing programs in a conventional manner: programmers have strong expectations that other programmers will follow these discourse rules.  If the rules are violated, then the utility afforded by the expectations that programmers have built up over time is effectively nullified.”  (P.733)

This is in alignment with the ideals of best practices.  The core concept is to have a codebase that exudes familiarity even to first time readers.  McConnell emphasizes the importance of the human aspect of coding:

“The smaller part of the job of programming is writing a program so that the computer can read it; the larger part is writing it so that other humans can read it.” (P.733)

Indeed, writing code so that the machine can read it is easy: the compiler, IDE, and development tools like ReSharper will tell you when the machine can’t read it.  Writing code so that other humans can read it is a true challenge since there is no one to confirm your view of the code or structure (without a well defined code review practice or pair programming).

In that sense, writing code is not so different than writing in general.  Using shorthand is always the fastest ways to write little notes for oneself, but when composing a written work that others must consume, there are certain conventions that people come to expect: proper spacing, proper usage of punctuation, proper grammar, and the usage of paragraphs to delineate discrete bodies of text – these details all help to make the text more readable from a mechanical perspective.

While code is certainly not literature (well, not to most normal people anyways ;-)), there are similar traits in elegant code structure and elegant prose: it is simple, clear, concise, and expressive.  It might follow a pattern (rhyming, iambic pentameter, etc.) that gives it a flow.

Soloway and Ehrlich’s studies concluded that:

“The results point out the fragility of programming expertise: advanced programmers have strong expectations about what programs should look like, and when those expectations are violated—in seemingly innocuous ways—their performance drops drastically.” (P.735)

They cite examples where advanced chess players showed a marked increase in ability to memorize chess pieces arranged in “standard” or common scenarios over novice players, but demonstrated no increased ability when the pieces were arranged in a random fashion.  The conclusion is that familiarity increases the ability to internalize and process an otherwise abstract structure (or in this case, arrangement of chess pieces).

Of course, it’s not all just fluff and “nice to haves”, right?  McConnell raises an interesting observation that:

“The information contained in a program is denser than the information contained in most books.  Whereas you might read and understand a page of a book in a minute or two, most programmers can’t read and understand a naked program listing at anything close to that rate.  A program should give more organizational clues than a book, not fewer.”

This makes the argument clear for commenting, proper and consistent application of white space, and using descriptive rather than short names (see Framework Design Guidelines for more coverage on that).  For example (and I’ve never understood this one), the use of “itm” instead of typing “item” or “tsk” instead of “task” or the use of “d” to declare a local variable instead of “document”.  One letter makes the code much more readable and much easier to process for another human reader of the code.

McConnell also makes a very good case for how code should be structured to reduce the complexity of the visual layout.  He gives a good abstract comparison on page 747.  These are small items which increase the readability of the code in very subversive ways; you probably never think about such details actively, but when processing a page of code, little details like indentation probably have a strong effect on your ability to understand the purpose and nature of the code.  More importantly, when other humans have to process your code, these little details, taken in cumulative, could mean the difference between a day of ramp up and a week of ramp up time.

Of course, McConnell does acknowledge that in many cases, such matters of style are borderline “religious”.  But from an objective perspective:

“…it’s clear that some forms of layout are better than others.  Good programmers should be open-minded about their layout practices and accept practices proven to be better than the ones they’re used to, even if adjusting to a new method results in some initial discomfort.” (P.735)

Definitely a book that deserves some shelf space on any developer’s desk (edit: or nightstand ;-)).