List:Internals« Previous MessageNext Message »
From:Michael Widenius Date:June 24 2009 2:50pm
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
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.

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.

Regards,
Monty
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