In article <1993Sep16.062437.12259@csis.dit.csiro.au> bmodra@mizar.csis.dit.csiro.au (Brian Modra) writes:

   I'm a programmer who hates code which is full of comments.
   We are taught that a program must have lots of comments in it.
   In other words, write a document, and just to make it legitimate,
   put a few lines of code in here and there!

   When I am confronted with someone elses code, and told to use it,
   I sit looking at it with a deepening feeling of perplexity. Then
   I finally get motivated, and delete all comments but the
   headers (those before or after a function) and the variable
   explanations (those at the end of a line with variable declarations
   or function parameters.) Then I can "READ" the code! All of a sudden,
   it starts to make sense...

   There's a feeling that thousands of other programmers agree with me
   wholeheartedly but have a guilt complex about their own 'weakness'...

   [example elided]


Agreed. Other reasons to use comments:

1. You have imported a data structure  that does not satisfy
the common idiom,  e.g. FORTRAN arrays   and indices to  it.
This does not mean you should write  a lot, only a hint: "be
careful".

2. You have  for  some reason, e.g. numerical  stability, to
write a statement that appears silly, too complicated or not
well thought.  You *must* warn the  programmer not to change
this unless  he knows what he  does,  and inform  the reader
about your intent.

3. You are inserting a quick  hack into the code. Preferably
the old code is left in the comment.  I  try to enclose such
statements  with   cpp-conditionals,  but  it's   not always
reasonable. You have to state *why* you hacked it.

Hello out there.

I'm a programmer who hates code which is full of comments.
We are taught that a program must have lots of comments in it.
In other words, write a document, and just to make it legitimate,
put a few lines of code in here and there!

When I am confronted with someone elses code, and told to use it,
I sit looking at it with a deepening feeling of perplexity. Then
I finally get motivated, and delete all comments but the
headers (those before or after a function) and the variable
explanations (those at the end of a line with variable declarations
or function parameters.) Then I can "READ" the code! All of a sudden,
it starts to make sense...

There's a feeling that thousands of other programmers agree with me
wholeheartedly but have a guilt complex about their own 'weakness'...

How's this for a well documented function:

// Author:              Joe Blogs
// Date created:        10/11/2027
// Modified:

// Purpose:             String concatenation
//      This function is like strcat, except it automatically
//      reallocates the source string to fit the new one....
//      (Comment from IT manager: why not create a String class?)

void
strCat(char** src, char* add)
//      src is a pointer to the source string
//      add is the string to cat to src.
{
        if (src == NULL) return;                             // Note A
        if (add == NULL) return;

        int add_len = strlen(add);
        if (*src == NULL)
        {
                *src = new char[add_len+1];                  // Note B
                strcpy(*src, add);
        }
        else
        {
                int src_len = strlen(*src);
                char* ptr = new char[src_len + add_len + 1]; // Note B
                strcpy(ptr, *src);
                strcpy(ptr+src_len, add);
                delete [] (*src);
                *src = ptr;
        }
}

// Note A:      verify parameters are sensible
// Note B:      no checking that Free store allocation succeeded...
///////////////////////////////////////////////// end of strCat

OK... this will draw in some flames!! Hope it gets some cheers also!

Brian Modra