Click here to Skip to main content
14,242,230 members

Minimalist Comments

Rate this:
4.83 (10 votes)
Please Sign up or sign in to vote.
4.83 (10 votes)
30 May 2013CPOL
This article presents arguments in favor of adopting Mimimalist 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.

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):

    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.

Specious Comments [^]

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

/* 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

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):

{ compute sum of values 14 to 741 }
  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.


    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


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Software Developer (Senior)
United States United States
I started programming more than 42 years ago using AutoCoder and RPG (note no suffixing numbers). Programs and data were entered using punched cards. Turnaround between submitting a job for compilation and execution was about 3 hours. So much for the "good old days!" Today, I particularly enjoy programming real-time software. I consider myself capable in WinForms, Mobile Apps, and C# although there are occasions that I yearn to return to C and the Win32 API.

Comments and Discussions

QuestionGreat Pin
Susan Nelson20-May-18 21:20
memberSusan Nelson20-May-18 21:20 
GeneralMy vote of 4 Pin
Dr. Jones DK4-Jun-13 9:58
professionalDr. Jones DK4-Jun-13 9:58 
GeneralRe: My vote of 4 Pin
gggustafson10-Jun-13 4:57
professionalgggustafson10-Jun-13 4:57 
GeneralMy vote of 5 Pin
Dave Cross3-Jun-13 22:07
professionalDave Cross3-Jun-13 22:07 
GeneralRe: My vote of 5 Pin
gggustafson4-Jun-13 3:40
professionalgggustafson4-Jun-13 3:40 
GeneralMy vote of 4 Pin
HeWillem3-Jun-13 20:12
memberHeWillem3-Jun-13 20:12 
GeneralRe: My vote of 4 Pin
gggustafson4-Jun-13 3:37
professionalgggustafson4-Jun-13 3:37 
GeneralRe: My vote of 4 Pin
HeWillem4-Jun-13 5:18
memberHeWillem4-Jun-13 5:18 
GeneralRe: My vote of 4 Pin
gggustafson10-Jun-13 6:20
professionalgggustafson10-Jun-13 6:20 
QuestionGood article. Pin
PauloJuanShirt30-May-13 21:59
memberPauloJuanShirt30-May-13 21:59 
AnswerRe: Good article. Pin
gggustafson31-May-13 4:21
professionalgggustafson31-May-13 4:21 
GeneralMy vote of 5 Pin
GregoryW30-May-13 20:12
memberGregoryW30-May-13 20:12 
GeneralRe: My vote of 5 Pin
gggustafson31-May-13 4:19
professionalgggustafson31-May-13 4:19 
GeneralRe: My vote of 5 Pin
GregoryW31-May-13 5:25
memberGregoryW31-May-13 5:25 
GeneralRe: My vote of 5 Pin
gggustafson31-May-13 8:23
professionalgggustafson31-May-13 8:23 
GeneralI agree with caveats Pin
Nic_Roche30-May-13 12:33
professionalNic_Roche30-May-13 12:33 
GeneralRe: I agree with caveats Pin
gggustafson31-May-13 4:02
professionalgggustafson31-May-13 4:02 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Posted 30 May 2013

Tagged as



9 bookmarked