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
