List:Internals« Previous MessageNext Message »
From:MARK CALLAGHAN Date:June 24 2009 3:36pm
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
On Wed, Jun 24, 2009 at 7:50 AM, Michael Widenius<monty@stripped> wrote:
>
> Hi!
>
>>>>>> "Jay" == Jay Pipes <Jay.Pipes@stripped> writes:
>
> Jay> Tor Didriksen wrote:
>>> hi
>>>
>>>
>>> "function and method comments should be placed in front of
>>> implementation rather than declaration"
>>>
>>> I find it quite strange that member functions should be documented in
>>> the .cc file rather than the .h file, especially if these are public
>>> member functions (part of the public interface of the class).
>
> Jay> I also find this strange.  API documentation should be with the
> Jay> declaration, not definition. This is how Drizzle does things, and also
> Jay> how a good chunk of the MySQL code base does things...
>
> Jay> Implementation-specific documentation should go in the source files (cc
> Jay> files).  For instance, details of an algorithm or *why* a structure is
> Jay> the way it is.  But, simple descriptions of an API's methods and
> Jay> structures, IMHO, should go in the header files next to the declaration,
> Jay> not definition/implementation.
>
> The reason for having things near the implementation is that a coder
> is more often working with the implementation and then it's a real
> pain to have to jump to the declaration while reading how functions
> should work.

I am not aware of any other projects that have done this. I have never
worked on code that has done this.

>
> Another reason for having the comment where the implementation is that
> this has a much bigger chance to assure that the comment and the code
> is up to date.
>
> With a good editor, you can jump to the implementation with a couple
> of key strokes and then you should have the full documentation for the
> code at hand.

I don't think that anyone on the core team at MySQL has the right
perspective to judge this. Headers help or hinder people new to the
code. When I want to figure out what a module can do in InnoDB, I read
the header file. Alas, code is not really modular in MySQL and the
header files that exist are huge and poorly documented (mysql_priv.h).
This is extremely discouraging for someone new. I put up with that
because I was/am paid to work on the code. People making voluntary
contributions will move on to Drizzle. I want some of the great things
being done in Drizzle to be repeated in traditional MySQL.

-- 
Mark Callaghan
mdcallag@stripped
Thread
MySql coding style: Request for change regarding documentation.Tor Didriksen22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Jay Pipes22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun
      • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN24 Jun
        • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Joerg Bruehe25 Jun
  • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov22 Jun
    • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
    • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
  • Re: MySql coding style: Request for change regarding documentation.Guilhem Bichot22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev23 Jun
        • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun