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
