[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