Re: Commenting functions

On Sat, 29 Dec 2007 13:30:30 -0600, amvoiepd@xxxxxxxxxxxx wrote
(in article
<97f490f3-43e0-43ae-87f6-0773517e8501@xxxxxxxxxxxxxxxxxxxxxxxxxxx>):

Hi!
I would like some help on deciding on a good way to write comments
that describes functions, like, it's parameters, return value and so
on.

A worthy goal, to be sure.


Take this for example:

/*
* Returns 1 if parent is parent of window.
*/
int is_parent_of(struct Win *parent, struct Win *window)
{
...
}

Not very nice when the same word is used as the name of one
parameter,

Pick better variable names? ;-)

how would I separate those two? And also describe
return values and similar in a systematic way?

Also should one write "Returns 1 if ... " or "Return 1 if ..." ?

*shrug* far from the biggest issue with commenting. Making sure they
start out, and remain accurate during maintenance over time is far more
important than grammar police.

I know this is a personal style matter, but since I really don't
know it would be nice to know if there is some widely used style.

There are probably several dozen "common" styles used, if you look at
various well known style-guides, and some of the larger open source
projects (those that actually have consistent commenting of code, that
is).

You'll also find that people using some of the automatic doc generation
packages that will take comments and turn them into html or pdf
documentation files with nice formatting automatically (like doxygen)
impose some "style" of their own in terms of special flag markers in
the comments to key the automated tool on how to parse the
comment block.


For general purposes, some subset or combination of the following isn't
uncommon, albeit a bit wordy, and also the more involved it is, the
less likely you, or anyone else will stick to it consistently in large
projects:

/*
* return_type function_name( ... parameter list ...)
*
* [description of function_name()'s purpose]
*
* [description of return value]
* [description of parameters 1 .. n with any caveats of import]
* Some people use IN, OUT, IN/OUT to flag whether or not the parms
* are modified, used for input, etc. others prefer things like
* const poisoning to indicate these things.
* [list external references for complicated issues, for example a
* function that implements some industry standard test sequence]
* [Warning about side-effects, such as global variables modified]
* [note on reentrancy if applicable]
* [Note on memory management assumptions, like if data is malloc'd
* and the caller is expected to free it later]
*/

Most of the time, simple functions need very little of the above,
and a simple notation of what the purpose is and anything that isn't
very obvious, or documented inline below is sufficient.

A simple function that is only 4 lines of simple, clear code does not
need 25 lines of comments to describe it, obviously.

Along the same idea, functions so complicated as to need all of the
above might very well deserve being looked at to simplify them. ;-)

For long parameter lists, sometimes you will see this variant:

return_type
bloated_api( int somevalue, /* comment about somevalue */
foobar_t *foo, /* comment about foo */
void *uglyp, /* comment about uglyp */
...
...
)
{
/* body */
}





--
Randy Howard (2reply remove FOOBAR)
"The power of accurate observation is called cynicism by those
who have not got it." - George Bernard Shaw





.