• Choose a category
• All
• Classic-Fiction

By Root 5019 0

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.[]

[] One comment in DiffMerge does describe a change: "2-18-97 (seiwald) - translated to C++." This comment remains in the code as a historical curiosity.

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.

Code in Motion > The Tools We Use

32.5. The Tools We Use

Certainly we need code to be understandable when we read the source files directly. We also need the code to be understandable when we encounter it in diffs, merges, patches, debuggers, code inspections, compiler messages, and a variety of other contexts and tools. As it turns out, code written with the Seven Pillars in mind is more readable in more of the tools we use to manage code.

For example, DiffMerge code is human-readable even without syntax highlighting. In other words, we don't have to depend on context-sensitive source code editors to read it. It's just as readable when displayed as plain text by debuggers, compilers, and web browsers. Here's a snippet of DiffMerge in gdb:

Code View: Scroll / Show All

Breakpoint 3, DiffMerge::DiffDiff (this=0x80e10c0) at diff/diffmerge.cc:510

510 Mode initialMode = d.mode;

(gdb) list 505,515

505 DiffGrid d = diffGrid

506 [ df1->StartLeg() == 0 ][ df1->StartBase( ) == 0 ]

507 [ df2->StartLeg() == 0 ][ df2->StartBase( ) == 0 ]

508 [ df3->StartL1() == 0 ][ df3->StartL2( ) == 0 ];

509

510 Mode initialMode = d.mode;

511

512 // Pre-process rules, typically the outer snake information

513 // contradicts the inner snake, its not perfect, but we use

514 // the length of the snake to determine the best outcome.

515

(gdb) print d

$1 = {mode = CONF, diffs = DD_CONF}

(gdb)

When