From: MARK CALLAGHAN Date: June 23 2009 3:22am Subject: Re: MySql coding style: Request for change regarding documentation. List-Archive: http://lists.mysql.com/internals/36957 Message-Id: MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Mon, Jun 22, 2009 at 8:34 AM, Konstantin Osipov w= rote: > * Tor Didriksen [09/06/22 17:53]: >> "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). > > We had this discussion already, opinions got split back then. > > There were two major reasons to keep comments close to > implementation: > > > 1) This is how it was before we moved to doxygen, so we just > =A0 updated syntax of most comments without moving them around. > =A0 We try to preserve contingency of revision history when > =A0 possible. From the proposal on refactoring, the code is about to undergo major changes. Why not fix this in the same process (or allow for this to be fixed)? And by 'fix' I mean that the current approach is broken, a worst-practice, would make me fail my undergrad software engineering course, makes me unhappy, ... > 2) It was proclaimed back then that keeping comments closer to > =A0 implementation would make them easier to maintain. Comments in the header describe the interface. Comments in the source describe how the implementation achieves the interface. The interface is less likely to change. --=20 Mark Callaghan mdcallag@stripped