From: MARK CALLAGHAN Date: April 6 2010 2:55pm Subject: Re: doxygen comments in header files List-Archive: http://lists.mysql.com/internals/37850 Message-Id: MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 On Tue, Apr 6, 2010 at 5:56 AM, Michael Widenius wrote: > > Hi! >>> I know the current rule is liked by some and has upset others, so I >>> suggest this be discussed by the Coding style committee (note: I'm not >>> in it anymore). > > However, for someone trying to read or debug the code, having the > comments in the header file can be a nightmare. Pardon the lousy argument, but the rest of the world disagrees with you. Documenting the interface in a header file is a standard practice. Too much code has no comments -- neither in the header file nor in the implementation. There are no comments at the start of header files to describe major subsystems. This drives away the community as nobody will work on code like this unless they are paid. I have direct experience with this as my teams have lost talented people who were tired of working on undocumented code. Fortunately this appears to be changing for recently written code. -- Mark Callaghan mdcallag@stripped