From: Michael Widenius Date: June 24 2009 2:50pm Subject: Re: MySql coding style: Request for change regarding documentation. List-Archive: http://lists.mysql.com/internals/36982 Message-Id: <19010.15670.555858.832803@narttu.askmonty.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Hi! >>>>> "Jay" == Jay Pipes 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