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