Beautiful Code [342]
[] 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 go on."
Code is not strictly text, of course, but for the purpose of human readability, the same principles apply. Bookish code—that is, code formatted in book-like columns and chunks—is easier to comprehend.
Bookishness is more than simply keeping lines short. It's the difference between code that looks like this:
if( bf->end == bf->Lines() && lf1->end == lf1->Lines( ) &&
lf2->end == lf2->Lines( ) ) return( DD_EOF );
and code that looks like this:
if( bf->end == bf->Lines( ) &&
lf1->end == lf1->Lines( ) &&
lf2->end == lf2->Lines( ) )
return( DD_EOF );
The second of these code snippets is taken from DiffMerge. When we read it, our brains sense the scope of the logic at hand, and our eyes don't have to scan very far from side to side to take it in. (The fact that there's a visual pattern created by the choice of line breaks is also important; we'll get to that in a moment.) Being more bookish, the second snippet is easier to comprehend than the first.
Code in Motion > Alike Looking Alike
32.2. Alike Looking Alike
The DiffMerge snippet in the previous section also illustrates another principle of writing for comprehensibility: code that is alike looks alike. We see this throughout the DiffMerge code. For example:
while( d.diffs == DD_CONF && ( bf->end != bf->Lines( ) ||
lf1->end != lf1->Lines( ) ||
lf2->end != lf2->Lines( ) ) )
The preceding demonstrates how line breaks can create a visual pattern that makes it easier for our brains to recognize a logical pattern. We can tell at a glance that three of the four tests in this while statement are essentially the same.
Here's one more example of alike looking alike. This one illustrates coding that lets our brains do a successful "one of these is not the same" operation:
Code View: Scroll / Show All
case MS_BASE: /* dumping the original */
if( selbits = selbitTab[ DL_BASE ][ diffDiff ] )
{
readFile = bf;
readFile->SeekLine( bf->start );
state = MS_LEG1;
break;
}
case MS_LEG1: /* dumping leg1 */
if( selbits = selbitTab[ DL_LEG1 ][ diffDiff ] )
{
readFile = lf1;
readFile->SeekLine( lf1->start );
state = MS_LEG2;
break;
}
case MS_LEG2: /* dumping leg2 */
if( selbits = selbitTab[ DL_LEG2 ][ diffDiff ] )
{
readFile = lf2;
readFile->SeekLine(