List:Internals« Previous MessageNext Message »
From:MARK CALLAGHAN Date:April 6 2010 2:55pm
Subject:Re: doxygen comments in header files
View as plain text  
On Tue, Apr 6, 2010 at 5:56 AM, Michael Widenius <monty@stripped> wrote:
>
> Hi!

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

Pardon the lousy argument, but the rest of the world disagrees with
you. Documenting the interface in a header file is a standard
practice.

Too much code has no comments -- neither in the header file nor in the
implementation. There are no comments at the start of header files to
describe major subsystems. This drives away the community as nobody
will work on code like this unless they are paid. I have direct
experience with this as my teams have lost talented people who were
tired of working on undocumented code.

Fortunately this appears to be changing for recently written code.

-- 
Mark Callaghan
mdcallag@stripped
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