• Choose a category
• All
• Classic-Fiction

By Root 5233 0

working on code that changes as often as DiffMerge (it has been changed 175 times since it was first written), programmers spend considerable time looking at it in diff and merge tools. What these tools have in common is that they restrict the horizontal view of source files, and they add a certain amount of clutter of their own. Code like DiffMerge's is readable even in these conditions. In command-line diffs, its lines don't wrap. In graphical diff tools, we don't have to fiddle with the horizontal scroll bar to see the bulk of its lines, as Figure 32-1 demonstrates.[§]

[§] This is a screenshot from P4Merge, a graphical tool built on DiffMerge itself.

Figure 32-1. DiffMerge code viewed in a graphical diff tool

And as Figure 32-2 shows, a margin-hungry annotated history viewer is positively roomy when displaying the bookish DiffMerge code.

Figure 32-2. DiffMerge code in an annotated history viewer

Bookishness not only makes code more readable in merge tools, it makes the code itself easier to merge. For one thing, the scope of an edit is easier to control when logical blocks are set off by whitespace. And for another, having less nested code means having proportionally fewer instances of inverted and leapfrogged block delimiters to sort out.

Code in Motion > DiffMerge's Checkered Past

32.6. DiffMerge's Checkered Past

We have a record of every change, branch, and merge involving DiffMerge throughout its 10-year history. And it's an interesting record. Figure 32-3 offers a thumbnail view of changes to the released versions of DiffMerge. It shows that DiffMerge originated in the mainline (the lowest line on the diagram) and has been branched into over 20 releases. Changes to DiffMerge have occured in the mainline, for the most part. But the thumbnail shows peculiar activity in some of the most recent releases.

Figure 32-3. DiffMerge's release branches

A count of DiffMerge's patches per release branch, seen in Figure 32-4, is even more intriguing. It shows that DiffMerge was rarely patched after it was released—until the 2004.2 release, that is. Then the post-release patch rate soars, only to abate again in the 2006.2 release. Why are releases 2004.2 through 2006.1 so riddled with patches?

Here's the backstory: DiffMerge started out as a serviceable but simple program. In its early life, it did little to discriminate between actual merge conflicts and nonconflicting, adjacent-line changes. In 2004, we enhanced DiffMerge to be smarter about detecting and resolving conflicts. As of the 2004.2 release, DiffMerge was certainly more capable, but it was buggy. We got lots of bug reports in 2004.2 and 2005.1—hence the large number of patches. We tried to clean up the code for release 2005.2, but the cleanup resulted in a bug so intractable that we had to restore the 2005.1 version into the 2005.2 release. Then, in 2006, we rewrote the troublesome parts of DiffMerge completely. The rewrite was quite successful, although we did have to tweak it in release 2006.1. Since then, DiffMerge been very stable, and its post-release patch rate is back down to zero.

Figure 32-4. Number of patches applied to DiffMerge per release

So, what went wrong when we rewrote DiffMerge in 2004? We believe it was that we had let the code become incomprehensible. Perhaps our code reviews at the time had lost sight of the Seven Pillars, or perhaps we had skipped some reviews entirely. At any rate, although it continued to pass regression testing, DiffMerge sailed into release branches full of bugs we hadn't seen coming on board.

We have no way to measure how readable source code is or how well it conforms to the Seven Pillars. But in retrospect, we see a clue that would have leapt out at us had we been looking for it at the time. Figure 32-5 shows a count of if statements and their successive nesting levels (as inferred from their indentation depths) in each initial branch of Diff-Merge. By the time we branched DiffMerge for 2004.2, apparently, we had doubled the number of if statements in the code. And for the first