I disagree with this. Comments before the function should document
_what_ the function does (and preferably what its inputs and output
are), while comments inside the function should, where necessary,
clarify _how_ it does this.
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 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. (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.
A hybrid scheme I have sometimes used in the past puts comments
inside function bodies only to provide markers to footnotes
given after the function body. For example, a function might
be written like this:
int
main(){
int c, n = 0;
while((c=getchar()) != EOF){
n = c == ' ' ? n+(n<2) : 0; // 1
if(n<2) putchar( c ); // 2
}
return 0;
}
/* Notes:
*
* [1] The variable 'n' holds a count of how many spaces
* have last been seen, limited to 2.
*
* [2] If 'n' is 0, the last character was a non-space and
* should be printed. If 'n' is 1, the last character
* was the first space in this sequence and should be
* printed. If 'n' is greater than 1, that indicates
* a space after the first in a sequence, which should
* not be printed.
*/
In my experience this approach is much better, on those occasions
when comments are called for, than putting comments directly
inside the body of a function.