List:Internals« Previous MessageNext Message »
From:Joerg Bruehe Date:June 25 2009 9:48am
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
Hi!


Michael Widenius wrote:
> Hi!
> 
>>>>>> "Jay" == Jay Pipes <Jay.Pipes@stripped> writes:
> 
> [[...]]
> 
> 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 find it a very weird assumption that the developers (in general)
should deal more often with the implementation of a function than with
using it.
Assuming (for simplicity) that the maintenance likelihood is about the
same for all code, and that a function is called from more than one
place, it is obvious that more maintenance effort would be spent on the
calls than on the implementation.

Now I know these assumptions are gross simplifications, but still the
claim of "more often working with the implementation" is only valid for
the implementor of this specific function, not for the community of all
developers.

> 
> 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.

The question was about comments defining the function's API (parameters
and effects), not the implementation.
Your statement implies that the API would change - this is not what I
expect to happen.


Jörg

-- 
Joerg Bruehe,  MySQL Build Team,  Joerg.Bruehe@stripped
Sun Microsystems GmbH,   Komturstraße 18a,   D-12099 Berlin
Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Wolf Frenkel
Vorsitzender des Aufsichtsrates: Martin Haering     Muenchen: HRB161028

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