Hello,
Tor Didriksen a écrit, Le 06.04.2010 10:25:
> 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.
Sorry. In French C++ courses member functions are called "méthodes", and
apparently not in English :-)
> 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?)
In short I propose to not change it, because I worship revision history
in our complex product. That is, change it but only when touching the
code for another reason.
> If I write a new class with member functions, no problem, document the
> entire interface in the .h file.
yes
> 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?
I don't have a good answer. I'd say, if your class has 50 members and
you are just adding one, then don't move the existing 100s of lines of
comments around, rather use the old style for your new/changed member.
If you're doing major revamping of the class, switch to new style. But,
I don't see that a rule is possible here. "Common sense" + "agree with
reviewer" is my preferred choice.
> Please also see: http://lists.mysql.com/internals/36943
Yes. Not everybody in the community agrees, for example. Now I think
it's time that the committee, who has listened to all expressed
opinions, just votes and decides about doing or not doing the proposed
style change (and then necessarily makes someone unhappy).
It's a good time to take a decision, because new features with their .h
file are being developped.
