From: MARK CALLAGHAN Date: June 24 2009 3:36pm Subject: Re: MySql coding style: Request for change regarding documentation. List-Archive: http://lists.mysql.com/internals/36989 Message-Id: MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Wed, Jun 24, 2009 at 7:50 AM, Michael Widenius wrote= : > > Hi! > >>>>>> "Jay" =3D=3D 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. =A0API documentation should be with the > Jay> declaration, not definition. This is how Drizzle does things, and al= so > 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). =A0For instance, details of an algorithm or *why* a structur= e is > Jay> the way it is. =A0But, simple descriptions of an API's methods and > Jay> structures, IMHO, should go in the header files next to the declarat= ion, > 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 am not aware of any other projects that have done this. I have never worked on code that has done this. > > 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. I don't think that anyone on the core team at MySQL has the right perspective to judge this. Headers help or hinder people new to the code. When I want to figure out what a module can do in InnoDB, I read the header file. Alas, code is not really modular in MySQL and the header files that exist are huge and poorly documented (mysql_priv.h). This is extremely discouraging for someone new. I put up with that because I was/am paid to work on the code. People making voluntary contributions will move on to Drizzle. I want some of the great things being done in Drizzle to be repeated in traditional MySQL. --=20 Mark Callaghan mdcallag@stripped