Beautiful Code [80]
In this chapter, we'll see how the Seven Pillars have supported a piece of code that has been part of a commercial software system for over 10 years. That piece of code is DiffMerge, a component of the Perforce software configuration management system. DiffMerge's job is to produce a classic three-way merge, comparing two versions of a text file ("leg 1" and "leg 2") to a reference version ("the base"). The output interleaves lines of the input files with placeholders marking the lines that conflict. If you've used Perforce, you've seen DiffMerge at work in the p4 resolve command and in Perforce's graphical merge tools.
DiffMerge was originally written in 1996. Despite its simple goal, a three-way text merge function turns out to be fraught with intricacy. It's a melting pot of special cases arising from the idiosyncrasies of user interfaces, character encodings, programming languages, and programmers themselves. ("That's not a conflict." "Yes, it is." "No, it's not!")
Over the years DiffMerge has become a locus of significant development at Perforce Software. So, it's not good enough that DiffMerge is simply a correct piece of code. It has to be a piece of code that "plays nice" with the tools we use for coding, debugging, and change management. And it has to be a piece of code that anticipates being changed.
The road from DiffMerge's first implementation to its present-day form has been uneven, to say the least. It's probably no coincidence that the further we strayed from the Seven Pillars, the rockier the road became. Later in this chapter, we'll reveal some of the potholes (and one major wreck) that beset DiffMerge's 10-year journey.
All's well that ends well, however. Today's DiffMerge, reprinted at http://www.perforce.com/beautifulcode, is stable and accepts enhancements with ease. It is a demonstration of how coding in anticipation of future change can produce a beautiful piece of code in motion.
32.1. On Being "Bookish"
"The Seven Pillars of Pretty Code" describes guidelines we use at Perforce Software. The Seven Pillars[] aren't the only coding guidelines we use, nor are they applied to all of our development projects. We apply them to components such as DiffMerge where the same code is likely to be active in several concurrently supported releases and modified by many programmers. The effect of the Seven Pillars is to make code more comprehensible to the programmers who read it, in more of the contexts in which they find themselves reading it.
[] And no, we don't call them "The Seven Pillars" back at the office. In fact, we don't really think of them as separate from our language- or component-specific coding guidelines. But when we strip out the latter, they are what's left.
Take, for example, the Seven Pillars' advice to be "bookish." Book and magazine text is composed in columns, usually in columns far narrower than the page. Why? Because narrowness reduces the back-and-forth scanning our eyes must do as we read—reading is easier when our eyes work less. Reading is also easier when what we've just read and what we're about to read are both within our visual range. Research shows that as our eyes change focus from word to word, our brains can take cues from surrounding, unfocused shapes. The more our brains can glean "advance warning" from shapes within the visual periphery, the better they're able to direct our eyes for maximum comprehension.
Research also seems to show that, when it comes to line lengths of text, there's a difference between reading speed and reading comprehension. Longer lines can be read faster, but shorter lines are easier to comprehend.
Chunked text is also easier to comprehend than a continuous column of text. That's why columns in books and magazines are divided into paragraphs. Paragraphs, verses, lists, sidebars, and footnotes are the "transaction markers" of text, saying to our brains, "Have you grokked everything so far? Good, please