List:Internals« Previous MessageNext Message »
From:Tor Didriksen Date:June 25 2009 7:18am
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
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



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