32.4. Navigating Code
All Seven Pillars are illustrated in DiffMerge, to one extent or another. For example, the DiffMerge code is constructed of discrete, logical blocks. Each block does a single thing or single kind of thing, and what it does is either self-evident or described in a comment that prefaces the block. Code like this is the result of the Seven Pillars' advice to disentangle and comment code blocks. It's analogous to well-organized expository writing, where definition lists and titled sections help readers navigate densely packed technical information.
The lack of clutter also makes the DiffMerge code easier to navigate. One of DiffMerge's clutter-reducing tricks is to use tiny names for variables that are referenced repeatedly throughout the code. This goes against sage advice to use meaningful and descriptive variable names, to be sure. But there's a point at which overuse of long names creates so much clutter that it only impedes comprehension. Writers know this; it's why we use pronouns, surnames, and acronyms in our prose.
The comments in DiffMerge are also clutter-free. In 10-year-old code, it's easy to end up with as many comments that describe how the code used to work—along with additional comments about what changed—as comments that describe the current code. But there isn't really any reason to keep a running history of the program's evolution in the code itself; your source control management system has all that information and offers much better ways to track it. (We'll show examples in the next section.) The programmers working on DiffMerge have done a good job keeping the closets clean, as it were. The same goes for code. In DiffMerge, the old code isn't simply commented out, it's gone. The remaining code and comments are uncluttered with the distractions of history.[
]
[
The DiffMerge code also makes liberal use of whitespace. In addition to reducing the appearance of clutter, whitespace increases comprehensibility. When bookish chunks and alike patterns are set off by whitespace, they take on visual shapes our brains can recognize. As we read through the code, our brains index these shapes; later, we unconsciously use these shapes to find code we remember having read.
Even though it has been changed repeatedly over the years, by many different programmers, the DiffMerge code is largely consistent in its visual appearance, DiffMerge's contributors have each made an effort to "blend in." That is, each one has subjugated personal style and preferences to make his DiffMerge code look like the rest of DiffMerge's code. Blending in produces a consistency that reduces the work our brains have to do. It effectively amplifies all of the readability tricks we've just discussed.
If you've visited http://www.perforce.com/beautifulcode, you will have noticed that the DiffMerge code isn't perfect, even by the Seven Pillars' standards. There are places where it could be more bookish, or where code could blend in more, for example. Sure, we'd like to clean those up, but while we like pretty code, we like clean merges even better. Changes to variable names, whitespace, line breaks, and so forth can be more of an obstacle to merging than logic changes. When we make changes like these in one branch, we increase the risk that merging bug fixes from other branches will create bugs. Any benefit to be gained by rewriting DiffMerge's ugly parts has to be weighed against the resources it could take to recover from a bad merge. In the section "DiffMerge's Checkered Past," we'll relate what happens when that scale tips.