Journeys
Rationale for Minimalist Comments
Journeys
Rationale for Minimalist Comments
I'm not sure when I stopped providing large amounts of commentary within computer programs. It was probably when I started programming in Pascal (having been programming in FORTRAN). I'm sure that the change in style came about as a result of the change in acceptable identifier name lengths. In those days (1978), FORTRAN allowed only six characters for identifier names while Pascal allowed 32. Thus the need to explain the sense of a variable diminished.
I believe that the suggestion that computer software be extensively commented flies in the face of good programming practice. This note discusses some of the issues surrounding my gradual adoption of minimalist commentary.
One type of comment that I have found is what I refer to as comments that should be variable names. Consider the following fragment (from a Pascal textbook that I used while teaching programming at Chapman University):
CONST
max = 100; { maximum test score }
How can this code be improved? I suggest that the constant be named maximum_test_score. Thus later in the source code, where the constant is referenced, rather than finding the somewhat cryptic max, we would find maximum_test_score.The improvement in readability is enormous.
Consider the following fragment:
/* compute the average of
the n observations */
a = 0.0F ;
if ( n )
{
s = 0 ;
for ( i = 0; ( i < n ); i++ )
{
s += v [ i ] ;
}
a = ( float ) s / ( float ) n ;
}
/* now compute the average
arrival time */
What's wrong with this code? I argue that the comments are not necessary if the variables were well named. By "well named," I mean that the variable names are drawn from the domain of the functional area. Thus, if the average is of ship speeds, then the code could take the following form.
average_ship_speed = 0.0F ;
if ( number_of_ships )
{
sum = 0 ;
for ( i = 0; ( i < number_of_ships ); i++ )
{
sum += speeds [ i ] ;
}
average_ship_speed = ( float ) sum /
( float ) number_of_ships ;
}
Another problem with the comments is their form. Within the body of the source code, I argue that only inline comments should be used. Suppose that the last line of the first comment was accidentally deleted. Now, without warning, the compiler will ignore all source code between the comment lines
/* compute the average of
arrival time */
If the author had used inline comments,
// compute the average of
// the n observations
// now compute the average
// arrival time
then if the last line of the first comment was accidentally deleted, no serious effect (other than loss of readability) occurs. A maintenance programmer would most likely find the error more quickly.
Of all the comment forms, the ones that are most dangerous are comments that are wrong. Consider the following fragment (from another Pascal textbook):
{ compute sum of values 14 to 741 }
FOR i := 741 DOWNTO 17 DO BEGIN
sum := sum + value [ i ] ;
END ;
This is a case of the comment being just plain wrong! Rather than compute to 14, the computation ends at 17. Needless to say confusion will arise when a maintenance programmer finds this comment. There are four options available:
I don’t like any of these choices. The comment could have been removed and the error avoided had the author not used literal constants in the code. Assuming that the values 741 and 17 have some special meaning in the problem domain, two constants with descriptive names should have been declared. Then those constants should have been used in the source code.
CONST
FIRST_SHIPMENT = 17 ;
LAST_SHIPMENT = 741 ;
FOR i := LAST_SHIPMENT DOWNTO FIRST_SHIPMENT DO BEGIN
sum := sum + shipment [ i ] ;
END ;
Another source of commentary problem occurs when a comment remains after the source code to which it referred has either been moved or deleted. Again, confusion will arise when a maintenance programmer finds the comment.
In writing my software, I use the following guidelines: