List:Internals« Previous MessageNext Message »
From:Kristian Nielsen Date:April 6 2010 10:58am
Subject:Re: doxygen comments in header files
View as plain text  
Tor Didriksen <Tor.Didriksen@stripped> writes:

> On 2010-03-31 11:53, Guilhem Bichot wrote:

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

> 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?

Maybe I am taking some liberties in my interpretation of the coding standard
about putting documentation at the place of implementation. But I have always
interpreted it so that I would put documentation about the *interface* of a
member function in the header. And documentation about the *implementation* of
that member function in the .cc (unless it's inline in the .h).

After all, the interface is implemented in the header, while the code is
implemented in the .cc.

So if you put the comment in the header, this is a promise to other developers
that this interface can be expected to be somewhat stable, and the method can
be used just by understanding the documentation of the interface, without
regard to how the implementation is done.

On the other hand, if you do not want / cannot give such promise, there
probably is no such well-thought out interface, and the comment is probably
better placed near the implementation, which will need to be consulted anyway
to safely use the member function.

And from this perspective I am wondering if there really is that much
disagreement between the "document in the header" vs. the "document in the
.cc" camps?

Anyway, just my .02 cents,

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