Commenting the source code.

[Dan Pop]

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

Well written code seldom needs any comments, if the algorithm used is
known or trivial. If it isn't, the comments should describe the
algorithm, not the code implementing it.

There are exceptions (especially in the presence of micro-optimisation),
but they are exactly this: exceptions.

Most of the comments belong before functions, describing the purpose of
the function, unless it is obvious from the function name and interface.

Dan

 

[Eric Sosman]

One of our source files over at work is rife with comments about some
obscure kludges that had to be inserted and need to be removed in the
future. But over the course of the program's development, no one has
bothered to find out what these kludges exactly are, which part of the
code they affect, and how (or if) they can be removed. So the file still
has comments about "This kludge should be removed by version n" when
we're already in version n+2. Actually the whole file needs complete
replacing but no one has got around to designing a replacement.

Having dealt with many such "permanent temporary
fixes," I found myself wishing for a way to make the
compiler complain -- not now, but at some future date,
so the hack would work for the moment but would draw
attention to itself later on. At first, I thought the
compiler ought to have a construct for such things, but
I eventually changed my mind: The compiler, in and of
itself, is not a complete software engineering tool and
should not be (ab)used as such.

Still, one can often take advantage of assorted
preprocessor symbols that medium-to-large projects often
define. E.g.,

/* This ugly hack works well enough to let the rest
* of the system be tested usefully, but should be
* fixed before we actually release the product.
*/
#ifdef RELEASE
#error "Please fix before shipping"
#else
/* ugly hack goes here */
#endif

Symbols that discriminate "release" from "test" versions
are often useful for this purpose; so, too, are symbols that
specify product versions (you'll ship the hack in version 2.0,
but want to remember to fix it for 2.1). NDEBUG is sometimes
used this way, but "overloading" its meaning is not wonderful.
The main idea is to look for a symbol that will change at some
relevant point in the future, ideally a symbol that is somehow
connected with the need for the hack, and then to plant a time
bomb with a BIG comment explaining what the hack was for and
how to tell whether it can be dispensed with.

 

[Dan Pop]

In general I would say that even if it is a switch statement it is
probably still difficult to read. I would generally write a function for
any case of significant length and call that function.

This doesn't help when the switch has *many* cases. Such jumbo switches
are not very often, but there are cases when they provide the best
solution to a given problem. Of course, the code handling each case
should not exceed a few lines.

Dan

 

[Rob Thorpe]

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

I would also add: How do you know it's 500 lines long until you've
commented it. A particularly nasty function might require as many
lines of commentary as code, or even twice as many. A 100 line long
function may become ~250 lines long.

You can only assess the complexity of an idea by implementing it *and*
explaining it.

 

[Alan Balmer]

Groovy hepcat Profetas was jivin' on Fri, 22 Oct 2004 11:40:15 -0400
in comp.lang.c.
Re: Commenting the source code.'s a cool scene! Dig it!


Someone might, someplace in the World. But I don't.
Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole 500
line function works, in detail, in a single comment, otherwise you
will get distracted.

But do explain *what* that 500 line function does, in a single
comment.

I am often faced with entire programs which need significant study
just to determine what their purpose is.

 

[Ben Pfaff]

Still, one can often take advantage of assorted
preprocessor symbols that medium-to-large projects often
define. E.g.,

/* This ugly hack works well enough to let the rest
* of the system be tested usefully, but should be
* fixed before we actually release the product.
*/
#ifdef RELEASE
#error "Please fix before shipping"
#else
/* ugly hack goes here */
#endif

Wouldn't work at a company I work for, which does continuous
builds of both debug and release versions. People would get
upset that I'd broken the release build. Instead, I'd just file
it in the bug system as needing a fix before release.

 

[Flash Gordon]

On 25 Oct 2004 14:47:39 GMT

In <[email protected]> Flash Gordon


This doesn't help when the switch has *many* cases. Such jumbo
switches are not very often,

Well, since I said "In general" not "Always" that does contradict what I
said.

but there are cases when they provide the
best solution to a given problem. Of course, the code handling each
case should not exceed a few lines.

I've yet to find such a case myself, but I accept that it is possible.

 

[John Bode]

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.


Does anybody agree?

Profetas

Actually, the few times I comment as I go is when I'm working on
something relatively large and complex. Short and simple stuff I can
knock out quickly enough to keep it all in my head, but if I have to
refer back and forth to other files or documentation as I go, I
rapidly lose state.

 

[Randy Howard]

Well written code seldom needs any comments, if the algorithm used is
known or trivial.

I tend to agree, but I don't think that zero comments is the right
answer. Lightly (but accurately and appropriately) commented code suits
me fine.

Specifically, I don't think that having a comment on or near every line is
of any use at all, as more often than not the comments get out of date
(stale) with respect to their contents under such heavy commenting policies.

On the other hand, some of the most esoteric & bizarre code ever seen (seems
to be an epidemic amongst low level system and driver code) has few or no
comments at all. In one sense, if you can't figure out what that code is
doing, you probably shouldn't be in there. On the other hand, using it as
a test for the next guy, or a barrier to competition isn't a good thing
either.

I tend to write clear block comments at the top of a function describing
the intent, how it works, and why that approach was chosen if there
could be any controversy about that. If a well known algorithm is being
used for something, I give a source for it. I also tend to use longer
"self-commenting" variable names apart from loop variables, and comment
them once at declaration, and let the code speak for itself most other
places unless something is being done that is likely to be misunderstood,
or perhaps accidentally thought to be unnecessary. Examples of the
latter would include platform-specific code, performance optimizations
where the specifics used are critical for some purpose, or other very
complicated code that needs to be there for a non-obvious reason.

If it isn't, the comments should describe the algorithm, not the code
implementing it.

I agree. /* add one to x */ comments and their ilk are a waste of time.

Something like:

/* this code uses XYZ's Algorithm for Random BS extraction per the
* paper at http://randomlink.com/whatever
* At the time this code was implemented it represented the best
* known approach to this problem.
*/

Is the type of thing I do most for anything that might not be obvious
to J. Random Maintenance Programmer.

 

[Keith Thompson]

I agree. /* add one to x */ comments and their ilk are a waste of time.

A comment like /* add one to x */ is useful if and only if it's
something the reader doesn't already know. For example, you might
reasonably have

x ++; /* add one to x */

in the first chapter of a C tutorial.

 

[Ben Pfaff]

A comment like /* add one to x */ is useful if and only if it's
something the reader doesn't already know. For example, you might
reasonably have

x ++; /* add one to x */

in the first chapter of a C tutorial.

Maybe. But it sets a horrible example in that it implicitly
encourages readers to comment their code the same way.

 

[Rob Thorpe]

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.


Does anybody agree?

Profetas

It doesn't matter when you comment (within reason), so long as you do
it, and you don't let the comments become out of date.

I find the best way to do this is to comment the code as it's written
and the functions at the end, but that's just me.

 

[Mabden]

Maybe. But it sets a horrible example in that it implicitly
encourages readers to comment their code the same way.

I agree with Ben. The comment should give some explanation of the "why",
not the "what".
The comment should be something more like:

++x; /* move to next screen position */

BTW, ++x reads as "increment x", x++ reads as "do nothing, then
increment x", to me.

 

[Mabden]

"Profetas" <[email protected]> wrote in message

It doesn't matter when you comment (within reason), so long as you do
it, and you don't let the comments become out of date.

I find the best way to do this is to comment the code as it's written
and the functions at the end, but that's just me.

Comments should tell what is going on, without be too intrusive.
Something like this (for my Palm OS game) works for me:

/* Create and label the "Next Tile" box */
RctSetRectangle (&rect, NextTile_Left, NextTile_Top, NextTile_Width,
NextTile_Height);
WinFillRectangle (&rect, 0);
WinPaintRectangleFrame (simpleFrame, &rect);
WinDrawChars ("Next", 4, NextTile_Left+5, NextTile_Top+1);
WinDrawChars ("Tile", 4, NextTile_Left+8, NextTile_Top+Second_Line);

/* Create and label the "Score" box */
RctSetRectangle (&rect, Score_Left, Score_Top, Score_Width,
Score_Height);
WinFillRectangle (&rect, 0);
WinPaintRectangleFrame (simpleFrame, &rect);
WinDrawChars ("Score", 5, Score_Left+5, Score_Top+1);

 

[Giorgos Keramidas]

No one really comments afterward. they just say they will, but there is
never time.

Not to mention that the concentration is already lost in the realm of human
memory, and you might have forgotten already what it all is about.

Seriously now, there are two sorts of `complexity' involved here: algorithmic
complexity and source-level complexity.

The first type of complexity is an inherent property of the algorithms and
data structures used. In this case, extensive documentation of the source
code either in the form of comments or in the form of accompanying (but
external) documents, can help a lot. It also doesn't matter if you write
these sorts of comments when you're actually typing the source, because they
should have already been `written' in some form as part of the overall design.

The second type of complexity, the one that is a side-effect of the language,
the libraries and -- most importantly -- the coding style used, is also
something that comments can help a lot with. In this case, my experience
shows that comments should be written at about the same time as the source
code is typed. It's the best time to do so, because you have all the details
in your mind and you don't need to recall anything from something you did some
time ago.

So, Profetas, IMHO you're partly right... and partly wrong too.

 

[Giorgos Keramidas]

This doesn't help when the switch has *many* cases. Such jumbo switches
are not very often, but there are cases when they provide the best
solution to a given problem. Of course, the code handling each case
should not exceed a few lines.

I am also tempted to use lookup tables of handler functions in cases
like this. One expects this to be a bit slower though, as it requires
some overhead for a function call and calling inline functions through
function pointers is, well, not possible ;-)

 

[Dan Pop]

BTW, ++x reads as "increment x", x++ reads as "do nothing, then
increment x", to me.

You're in dire need of a clue about the semantics of these operators.
They both increment x at an *unspecified* moment, before the next sequence
point, as a side effect, but they yield different values. If their
values are discarded, all semantic differences disappear: the side effect
is identical.

Dan

 

[Dan Pop]

Well, since I said "In general" not "Always" that does contradict what I
said.


I've yet to find such a case myself, but I accept that it is possible.

Consider the code dealing with opcode mnemonics in an assembler. A jumbo
switch dealing with each mnemonic as a case (by the time you have checked
that it is a valid mnemonic you can also assign it a unique integer value:
its position in the valid mnemonic array) is the most natural approach.

Dan

 

[Keith Thompson]

Maybe. But it sets a horrible example in that it implicitly
encourages readers to comment their code the same way.

Good point.

On further thought, the semantics of the ++ operator should probably
be explained in the text, not as a comment in sample source code.
There's no reason a sample program, even in the first chapter of an
elementary tutorial, can't exhibit both good coding and good
commenting.

A comment like /* add one to x */ is useful only as an example of a
bad comment.

 

[Mabden]

In <[email protected]> "Mabden"

You're in dire need of a clue about the semantics of these operators.
They both increment x at an *unspecified* moment, before the next sequence
point, as a side effect, but they yield different values. If their
values are discarded, all semantic differences disappear: the side effect
is identical.

I know that. I just prefer the first way, as when I am reading the
source it "reads" better, to me. You may prefer the second way, and code
it any way you wish. Some people may prefer "x = x+1;", but I like
"++x;" which I read (in my mind) as increment x. YMMV.