Vitaliy wrote:

> [...] so why not:
> 
> /* SomeFunction:
>  *     Put comments about a function right before the function body,
>  *     preceding the comments with the function name and a colon.
>  *     You can then search for "SomeFunction:" to quickly find
>  *     the definiton.
> */
> 
> int8u SomeFunction(int8u argument)
> {
> [...]

I know that it is common (well, almost universal) to put function
descriptions above the initial definition statement. But I don't find this
useful at all. This form was developed before everybody had editors with
code folding capabilities. (You do have one, do you? :)

So when you look at a file of such code in your folding editor, with most
of the functions folded, and you unfold a function, what do you see? The
code of the function, as you should. But in order to see the function
description, you need to unfold the preceding function -- and if you do
this, you need to scroll down past its end to see the function comment you
wanted to see. Not very useful.

Because of this, I find the following form better:

int8u SomeFunction(int8u argument)
// Put comments about a function right before the function body,
// but after the function definition statement. This also makes it
// unnecessary to repeat the function name in the description, 
// as it is already "headed" by it. Searching for the function name
// (again, you do have an editor that has something like a "go to 
// definition" command, right? :) gets you right there.
{
  // ...
}

Gerhard

-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist