On Wed, 24 Jun 2009 16:50:30 +0200, 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.
'real pain'? must be a strange editor you are using :-)
>
> 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.
The point is to have the entire interface documented in one place,
rather than having it spread out in multiple places.
Description of 'what' and 'why' goes in the .h file,
description of 'how' goes in the .cc file.
>
> Regards,
> Monty
-- didrik
