Background
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.
Introduction
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.
Table of Contents
The symbol [^] returns the reader
to the top of the Table of Contents.
Comments that require Reconsideration [^]
The following forms of comments should be reconsidered in light of
these guidelines.
Comments that should be Variable Names [^]
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 was forced to use while teaching
programming at Chapman University):
CONST
max = 100;
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.
Specious Comments [^]
Consider the following fragment:
a = 0.0F ;
if ( n )
{
s = 0 ;
for ( i = 0; ( i < n ); i++ )
{
s += v [ i ] ;
}
a = ( float ) s / ( float ) n ;
}
:
:
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 functional domain of the problem 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 in this example is their form.
Within the statement 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 of the source code between the comment
lines
If the author had used inline comments,
and 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.
Wrong Comments [^]
Of all comment forms misuse, the one that is most dangerous is a
comment that is wrong. Consider the following fragment (from another
Pascal textbook):
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 up from 14 to 741, the computation is from 741 down to 17.
Needless to say confusion will arise when a maintenance programmer
finds this comment. There are four options available:
- Ignore the comment entirely.
- Remove the comment.
- Change the comment to reflect what the code actually does.
- Change the code to reflect what the comment says.
I don’t like any of these choices. The comment could have been
removed and the error avoided had the original 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 ;
Leftover Comments [^]
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. The solution to this problem is simply use only
inline comments in statement bodies.
Recommended Guidelines [^]
In writing software, I use the following guidelines:
- Use descriptive identifier names, drawn from the functional area
of the problem domain. To the extent possible, use no
abbreviations.
- Never use literals (other than 0, 1, or 2) in source code. Use
constants in their place.
- Minimize the use of comments. If a block comment is needed, use
the inline comment form.
Conclusion [^]
This article has presented arguments in favor of adopting
Mimimalist Comments.
History [^]
05/30/2013
| | Original Article
|
In 1964, I was in the US Coast Guard when I wrote
my first program. It was written in RPG (note no suffixing numbers). Programs and data were entered using punched cards. Turnaround was about 3 hours. So much for the "good old days!"
In 1970, when assigned to Washington DC, I started my MS in Mechanical Engineering. I specialized in Transportation. Untold hours in statistical theory and practice were required, forcing me to use the university computer and learn the FORTRAN language, still using punched cards!
In 1973, I was employed by the Norfolk VA Police Department as a crime analyst for the
High Intensity Target program. There, I was still using punched cards!
In 1973, I joined Computer Sciences Corporation (CSC). There, for the first time, I was introduced to a terminal with the ability to edit, compile, link, and test my programs on-line. CSC also gave me the opportunity to discuss technical issues with some of the brightest minds I've encountered during my career.
In 1975, I moved to San Diego to head up an IR&D project,
BIODAB. I returned to school (UCSD) and took up Software Engineering at the graduate level. After BIODAB, I headed up a team that fixed a
stalled project. I then headed up one of the two most satisfying projects of my career, the
Automated Flight Operations Center at Ft. Irwin, CA.
I left Anteon Corporation (the successor to CSC on a major contract) and moved to Pensacola, FL. For a small company I built their firewall, given free to the company's customers. An opportunity to build an
air traffic controller trainer arose. This was the other most satisfying project of my career.
Today, I consider myself capable.