C Programming Language 2nd Ed, Exercise 1.9 and 1.12, Solution suggestion.

[Jorgen Grahn]

I agree that differentiating /what/ comments and /how/ comments
is a good idea. That doesn't mean they should be spatially
separated necessarily, only that the two kinds be clearly
distinguished. Putting /what/ comments first and /how/ comments
afterwards is obviously one way of doing that.

Comments (of either kind) inside function bodies, on the other
hand, is a bad idea, a bad habit acquired at an early age where
it is used in examples as a teaching aid. The problem is that
although it might be helpful in teaching how to program, it is
not a good fit for doing actual development. Psychological
experiments in dual-mode cognition (such as code and comments)
show

....

I disagree, but at the same time I think:

- People sometimes over-comment inside functions (and struct
definitions), especially if they follow a work pattern where
they sketch the program flow as comments and then fill in
the code. Also, such comments sometimes make people spend
less time on making the code itself self-explanatory: choosing
good variable names and so on.

- It's not uncommon to find comments inside the code which
really should have come in the comment block /before/ it.

- In the end it's a matter of good judgement. It's a case-by-case
thing, how to express your intent clearly.

that people prefer to work exclusively in a single mode (ie,
the code mode in this case) once they have reached a certain
level of understanding with how things work.

Seems a bit bogus to me ... if the comments and the code operate in
different modes, one of them is done wrong! They should both be part
of a single message to the reader.

If OTOH you're saying "tuck away useless comments somewhere where I
can ignore them", then I agree.

(Unfortunately I
have lost track of where the paper is with a reference for those
results.) Putting comments inside function bodies actually slows
down developers who know what they are doing.

....

/Jorgen

 

[Richard Bos]

I agree that differentiating /what/ comments and /how/ comments
is a good idea. That doesn't mean they should be spatially
separated necessarily, only that the two kinds be clearly
distinguished. Putting /what/ comments first and /how/ comments
afterwards is obviously one way of doing that.

Comments (of either kind) inside function bodies, on the other
hand, is a bad idea, a bad habit acquired at an early age where
it is used in examples as a teaching aid.

I'm afraid I just have to continue to disagree. I want my comments
closest to the code they're about. This means comments about the
function as a whole go at the top of the function, and functions about
how a single line (or a couple of lines) do their job go with those
lines.
When I read code, I don't want to spend my time going back and forth
between the code and the comment. I know some people are now going to
tell me to write smaller functions, but those people are just being
silly and fundamentalist, and they know it.

Richard

 

[Tim Rentsch]

...

I disagree, but at the same time I think:

- People sometimes over-comment inside functions (and struct
definitions), especially if they follow a work pattern where
they sketch the program flow as comments and then fill in
the code. Also, such comments sometimes make people spend
less time on making the code itself self-explanatory: choosing
good variable names and so on.

I agree with all these.

- It's not uncommon to find comments inside the code which
really should have come in the comment block /before/ it.

That is my observation also. Especially deplorable is the
practice of putting a comment after the final right parenthesis
surrounding the function's parameters and before the initial
open brace enclosing the function's body.

- In the end it's a matter of good judgement. It's a case-by-case
thing, how to express your intent clearly.

In some sense this is my point - what needs expressing, and at
what level of detail? How does what needs expressing change
as a function of time and audience? Presuming we know what
needs expressing, how should it be expressed so as to both
improve comprehension and maximize developer effectiveness?
These questions are not primarily programming questions but
more in the realm of psychology, and most developers don't
have the background to form good judgments about how they
should be answered.

Seems a bit bogus to me ... if the comments and the code operate
in different modes, one of them is done wrong! They should both
be part of a single message to the reader.

Here I think is the crux of the matter. There is an unconscious
assumption that the reader is operating in a single cognitive
mode, or that there is only one message that needs delivering.
This assumption is wrong according to studies that have been
done: people think quite differently when they are approaching
something for the first time compared to how they think when
they (mostly) understand what is going on. What message is
needed is different in the different cases.

If OTOH you're saying "tuck away useless comments somewhere where
I can ignore them", then I agree.

It isn't that the comments are useless. They are useful in one
cognitive mode, but not useful, or even worse than useless, in
another cognitive mode. Here is a short example from a piece of
code posted recently (the posted code originally had no comment):

unsigned minimum = (RAND_MAX - (n-1)) % n; // 1
...


/* Notes:
*
* [1] This expression is mathematically equal to (RAND_MAX+1)%n.
* It is written this way to avoid the possibility of integer
* overflow. The calculated value gives the smallest value
* that can be converted so there are equally many values for
* each possible output, ie, so [ minimum .. RAND_MAX ] is of
* a size that is a multiple of n.

If one is seeing this code for the first time, and not familiar
with the general pattern, the comment is pretty helpful. But for
developers who already understand the pattern, the comment isn't
needed - they can read just the single program line and see what
it is doing essentially instantly. Putting the comment inside
the function body not only wouldn't help them, it would actually
slow them down. It's nice to have the comment there for those
developers who haven't seen this sort of thing before, but it's
also nice to have it out of the way for those who have. Writing
comments in the form of footnotes effectively serves the needs of
both audiences, which could of course be the same audience but at
different points in their respective experience histories.

 

[Tim Rentsch]

I'm afraid I just have to continue to disagree. I want my
comments closest to the code they're about. This means comments
about the function as a whole go at the top of the function, and
functions about how a single line (or a couple of lines) do their
job go with those lines.

Nothing wrong with having an opinion. In this case though the
opinion is at odds with the results of people who make it their
job to study such things carefully and thoroughly. For the sake
of discussion let me agree that this mode works reasonably well
for you. How do you know that isn't just familiarity and habit,
and if you had different habits you might find your effectiveness
improved? I don't mean this question rhetorically - if you were
approaching the question afresh and trying not to pre-judge the
different approaches, what would you do to factor earlier habits
(not just your own but also those of others) out of the results?

When I read code, I don't want to spend my time going back and
forth between the code and the comment.

A key point is that most of the time there will be no going back
and forth because developers familiar with the code don't need to
read the comments and won't read them. Putting comments inside
function bodies optimizes the 10% case at the expense of the 90%
case (or maybe 20/80, but whatever - clearly the balance favors
the second mode over the first).

I know some people are now going to tell me to write smaller
functions, but those people are just being silly and
fundamentalist, and they know it.

IME functionalizing more - ie, breaking large functions into
several smaller functional units - goes a long way toward
reducing the need for commenting, especially if the functions'
names are well-chosen. So I don't think suggestions along these
lines are just silly. However I agree that such functionalizing
won't eliminate the need for comments in all cases - it will
be reduced, but not completely eliminated.

 

[Kaz Kylheku]

A key point is that most of the time there will be no going back
and forth because developers familiar with the code don't need to
read the comments and won't read them. Putting comments inside
function bodies optimizes the 10% case at the expense of the 90%
case (or maybe 20/80, but whatever - clearly the balance favors
the second mode over the first).

You can put small "footnotes" into the code like /* 2 */, which reference
numbered points in a block comment elsewhere, perhaps above the function.

I followed this practice for a while more than fifteen years ago;
it works well.

It is based on the equivalent practice in text, because the issue is
essentially the same: we want to concentrate on the main idea, but need to give
background notes without cluttering it to those who are interested or who
require them.

The thing is, if code needs that many footnotes, maybe it's badly written.
These days I only write an in-line comment when there is something very tricky
going on (and usually such a thing is written by someone else, and I'm
add the comment after spending considerable time reverse engineering
the purpose of the statements which follow, so that someone doesn't have
to do it again after me.

E.g. /* This flag is being set here so that the when
the foo function is invoked in situation q out of function
bar, it will avoid taking actions x y z. */

 

[Jorgen Grahn]

Jorgen Grahn <[email protected]> writes:

[comments in code, long snip]

In some sense this is my point - what needs expressing, and at
what level of detail? How does what needs expressing change
as a function of time and audience? Presuming we know what
needs expressing, how should it be expressed so as to both
improve comprehension and maximize developer effectiveness?
These questions are not primarily programming questions but
more in the realm of psychology, and most developers don't
have the background to form good judgments about how they
should be answered.

Perhaps true -- but I think that if more programmers just
realized/were told that this aspect /exists/, they would do
significantly better -- without a degree in psychology.

And now that you mention it: I think a course in technical writing
(for lack of a better term) should have been part of the CS education
I had. That would have been more useful than many other things we did.

....

Here I think is the crux of the matter. There is an unconscious
assumption that the reader is operating in a single cognitive
mode, or that there is only one message that needs delivering.
This assumption is wrong according to studies that have been
done: people think quite differently when they are approaching
something for the first time compared to how they think when
they (mostly) understand what is going on. What message is
needed is different in the different cases.

I think I'm aware of some of those modes (I use several myself), and
perhaps unaware of others ... also time and energy is limited. I
suppose what I do is optimize for people like myself (rather easy),
and sometimes for people who I know personally, and who will work with
that code in the future (harder).

/Jorgen