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:

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