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
