[RFC] Coding Style: Function header comments?

Michael Adam ma at sernet.de
Wed Nov 28 22:03:07 GMT 2007


Jelmer Vernooij wrote:
> There is currently nothing in the coding style guide about comments
> above functions, explaining in one or two lines what the function does.
> It would be nice to have a standard for this as well. 

> /************************************************************************
>  * Foo bar
>  **********************************************************************/
> 
> This is too much typing, and all the asterisks have no use imho :-)

This is the one I like most, aesthetically, at least if the line
lengths are made equal: It is symmetric, and it makes the comment 
and therefore the beginning of the function optically stand out nicely.

The "typing" argument does not count IMHO.
You can copy/paste or use some editor macros.

> /**
>  * Foo bar
>  */

I don't like it much optically, but the possibility of
auto-generating api documentation is of course a great
advantage. 

> This is the style used by doxygen and javadoc, and the one I like most.
> Optionally, we could allow /** foo bar */. The advantage of using this
> is that it allows using doxygen to generate API documentation, even if
> we don't use all the fancy stuff for documenting individual parameters.

Cheers - Michael

-- 
Michael Adam <ma at sernet.de>
SerNet GmbH, Bahnhofsallee 1b, 37081 Göttingen
phone: +49-551-370000-0, fax: +49-551-370000-9
AG Göttingen, HRB 2816, GF: Dr. Johannes Loxen
http://www.SerNet.DE, mailto: Info @ SerNet.DE
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 206 bytes
Desc: not available
Url : http://lists.samba.org/archive/samba-technical/attachments/20071128/5ad33b2a/attachment.bin


More information about the samba-technical mailing list