Hello,
this has been debated in the past but not in the coding style committee
recently, so here it is.
http://forge.mysql.com/wiki/MySQL_Internals_Coding_Guidelines says
"Put a comment in front of its subject. In particular, function and
method comments should be placed in front of implementation rather than
declaration. Class comments should be put in front of class declaration."
Even though I obey the rule, and enforce it on others when I'm code
reviewer, I would like the rule to be changed at least for class
methods: I would like their comment to be in front of the declaration
(so inside the class declaration). In short and approximatively: in the
".h" file, not in the ".cc" file.
Like this:
class C
{
/** comment (@param etc @retval etc) */
method();
}
My reasons:
1) imagine a class with members, pure virtual methods, inline methods,
and non-inline methods. The three first have their definition in the
class's declaration, and only the fourth has its definition in the .cc
file. Then the current rule suggests this:
class C
{
member; /** comment */
pure virtual method; /** comment */
method; /** no comment, as definition is in .cc */
inline_method { code }; /** comment */
}
and I find this inconsistent: only for "method" do you have to look up
the comment in the .cc file.
2) if I want to help the API user, who in theory can ignore the
implementation (the .cc) and concentrate on the API (the .h), it's
better if descriptive comments are in the .h. The comment in the .h can
tell what to give to the method and what to expect from it, that's all
the API user needs to know.
3) it's also easier for design reviews: if descriptive comments are in
the .h I can just paste the .h to the design reviewer, it makes a
self-documenting design.
I know the current rule is liked by some and has upset others, so I
suggest this be discussed by the Coding style committee (note: I'm not
in it anymore).
Thanks!
--
Mr. Guilhem Bichot <guilhem@stripped>
Sun Microsystems / MySQL, Lead Software Engineer
Bordeaux, France
www.sun.com / www.mysql.com
