From: Michael Widenius
Date: April 6 2010 12:56pm
Subject: Re: doxygen comments in header files
List-Archive: http://lists.mysql.com/internals/37848
Message-Id: <19387.12156.398380.800753@narttu.askmonty.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit


Hi!

>>>>> "Tor" == Tor Didriksen <Tor.Didriksen@stripped> writes:

Tor> 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.

Here you are optimizing for one case, but forget the other cases..

>> 
>> 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).

However, for someone trying to read or debug the code, having the
comments in the header file can be a nightmare.

Another issue that if you have a lot of classes and sub classes, it's
not good that all the comments for the sub classes methods are in the
header file, as this makes it hard to have slightly different comments
for each virtual function / pre class.

A good function / method comment doesn't only include only return
value and parameters, but also how the function is implemented, notes,
future suggestions and so on.  For the function comment in the .cc
file to make sense, you want to have all information there and not
having to look at many places how a function usage parameter may be
implemented.

I don't mind if you duplicate some shorter information in the .h file,
but don't remove it from the .cc file.

Regards,
Monty