On 2010-03-31 11:53, Guilhem Bichot wrote:
> 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!
>
Thanks Guilhem.
Nitpick about terminology first: there are no 'methods' in C++, there
are member functions.
About your suggestion: I, and I think many others, agree with your
suggestion.
The main problem is implementation: how do you propose to change
existing code (if at all?)
If I write a new class with member functions, no problem, document the
entire interface in the .h file.
If I add a member function to a class, where should I document it? new
or old style?
If I change a member function of a class, should I move the documentation?
Please also see: http://lists.mysql.com/internals/36943
-- didrik
