List:Internals« Previous MessageNext Message »
From:Tor Didriksen Date:April 6 2010 8:25am
Subject:Re: doxygen comments in header files
View as plain text  
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

Thread
doxygen comments in header filesGuilhem Bichot31 Mar
  • Re: doxygen comments in header filesTor Didriksen6 Apr
    • Re: doxygen comments in header filesGuilhem Bichot6 Apr
      • Re: doxygen comments in header filesMats Kindahl6 Apr
    • Re: doxygen comments in header filesKristian Nielsen6 Apr
      • Re: doxygen comments in header filesGuilhem Bichot9 Apr
        • Re: doxygen comments in header filesTimour Katchaounov11 Apr
          • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesSergei Golubchik11 Apr
              • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                    • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesSergei Golubchik12 Apr
            • Re: doxygen comments in header filesMichael Widenius13 Apr
              • Re: doxygen comments in header filesDavi Arnaut13 Apr
    • Re: doxygen comments in header filesMichael Widenius6 Apr
      • Re: doxygen comments in header filesMARK CALLAGHAN6 Apr
        • Re: doxygen comments in header filesMichael Widenius13 Apr
  • Re: doxygen comments in header filesDavi Arnaut7 Apr
    • Re: doxygen comments in header filesGuilhem Bichot7 Apr
    • Re: doxygen comments in header filesKonstantin Osipov9 Apr
  • Re: doxygen comments in header filesIngo Strüwing12 Apr
    • Re: doxygen comments in header filesGuilhem Bichot15 Apr
      • Re: doxygen comments in header filesIngo Strüwing15 Apr
        • RE: doxygen comments in header filesVladislav Vaintroub16 Apr