32.2. Programming Style as Documentation

In contrast to external documentation, internal documentation is found within the program listing itself. It's the most detailed kind of documentation, at the sourcestatement level. Because it's most closely associated with the code, internal documentation is also the kind of documentation most likely to remain correct as the code is modified.

The main contributor to code-level documentation isn't comments, but good programming style. Style includes good program structure, use of straightforward and easily understandable approaches, good variable names, good routine names, use of named constants instead of literals, clear layout, and minimization of control-flow and data-structure complexity.

Here's a code fragment with poor style:

Java Example of Poor Documentation Resulting from Bad Programming Style

for ( i = 2; i <= num; i++ ) { meetsCriteria[ i ] = true; } for ( i = 2; i <= num / 2; i++ ) { j = i + i; while ( j <= num ) { meetsCriteria[ j ] = false; j = j + i; } } for ( i = 1; i <= num; i++ ) { if ( meetsCriteria[ i ] ) { System.out.println ( i + " meets criteria." ); } }

What do you think this routine does? It's unnecessarily cryptic. It's poorly documented not because it lacks comments, but because it lacks good programming style. The variable names are uninformative, and the layout is crude. Here's the same code improved just improving the programming style makes its meaning much clearer:

Java Example of Documentation Without Comments (with Good Style)

for ( primeCandidate = 2; primeCandidate <= num; primeCandidate++ ) {    isPrime[ primeCandidate ] = true; } for ( int factor = 2; factor < ( num / 2 ); factor++ ) {     int factorableNumber = factor + factor;     while ( factorableNumber <= num ) {         isPrime[ factorableNumber ] = false;         factorableNumber = factorableNumber + factor;     } } for ( primeCandidate = 1; primeCandidate <= num; primeCandidate++ ) {    if ( isPrime[ primeCandidate ] ) {       System.out.println( primeCandidate + " is prime." );    } }

Cross-Reference

In this code, the variable factorableNumber is added solely for the sake of clarifying the operation. For details on adding variables to clarify operations, see "Making Complicated Expressions Simple" in Section 19.1.

Unlike the first piece of code, this one lets you know at first glance that it has something to do with prime numbers. A second glance reveals that it finds the prime numbers between 1 and Num. With the first code fragment, it takes more than two glances just to figure out where the loops end.

The difference between the two code fragments has nothing to do with comments neither fragment has any. The second one is much more readable, however, and approaches the Holy Grail of legibility: self-documenting code. Such code relies on good programming style to carry the greater part of the documentation burden. In well-written code, comments are the icing on the readability cake.

cc2e.com/3252

Checklist: Self-Documenting Code

Classes

• Does the class's interface present a consistent abstraction?

• Is the class well named, and does its name describe its central purpose?

• Does the class's interface make obvious how you should use the class?

• Is the class's interface abstract enough that you don't have to think about how its services are implemented? Can you treat the class as a black box?

Routines

• Does each routine's name describe exactly what the routine does?

• Does each routine perform one well-defined task?

• Have all parts of each routine that would benefit from being put into their own routines been put into their own routines?

• Is each routine's interface obvious and clear?

Data Names

• Are type names descriptive enough to help document data declarations?

• Are variables named well?

• Are variables used only for the purpose for which they're named?

• Are loop counters given more informative names than i, j, and k?

• Are well-named enumerated types used instead of makeshift flags or boolean variables?

• Are named constants used instead of magic numbers or magic strings?

• Do naming conventions distinguish among type names, enumerated types, named constants, local variables, class variables, and global variables?

Data Organization

• Are extra variables used for clarity when needed?

• Are references to variables close together?

• Are data types simple so that they minimize complexity?

• Is complicated data accessed through abstract access routines (abstract data types)?

Control

• Is the nominal path through the code clear?

• Are related statements grouped together?

• Have relatively independent groups of statements been packaged into their own routines?

• Does the normal case follow the if rather than the else?

• Are control structures simple so that they minimize complexity?

• Does each loop perform one and only one function, as a well-defined routine would?

• Is nesting minimized?

• Have boolean expressions been simplified by using additional boolean variables, boolean functions, and decision tables?

Layout

• Does the program's layout show its logical structure?

Design

• Is the code straightforward, and does it avoid cleverness?

• Are implementation details hidden as much as possible?

• Is the program written in terms of the problem domain as much as possible rather than in terms of computer-science or programming-language structures?