From: MARK CALLAGHAN Date: March 18 2009 3:18pm Subject: Re: [style] change proposal: function parameter names in headers List-Archive: http://lists.mysql.com/internals/36435 Message-Id: MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Wed, Mar 18, 2009 at 3:16 AM, Konstantin Osipov wrote: > * Mats Kindahl [09/03/18 11:32]: >> One thing that I am missing is a rationale... it is very hard to >> make a decision on why a particular style should be implemented, >> unless there is some kind of reason to why it should be >> implemented. > > Let's if I understand the rationale correctly: > > The rationale for the first is simplification of the rules. > > The rationale for the second is increased code clarity (for the > cost of increased maintenance burden and some difficulties with ctags). Documenting interfaces reduces the maintenance burden. Code is written a few times and read infinitely many times. Comments about the implementation may be incorrect but are still better than no comments as they give me a clue about what the code is trying to do at some point in time. InnoDB is a great example of how to write code that others can read and understand. InnoDB also happens to get large changes from the community. It has great documentation for interfaces, module comments at the start of source files and structure (source and headers are split into multiple files by functionality), modules use separate subdirectories. It also names variables and functions consistently using module prefixes (trx_, buf_, ...). > > -- > > -- > MySQL Internals Mailing List > For list archives: http://lists.mysql.com/internals > To unsubscribe: =A0 =A0http://lists.mysql.com/internals?unsub=3Dmdcallag@= gmail.com > > --=20 Mark Callaghan mdcallag@stripped