List:Internals« Previous MessageNext Message »
From:MARK CALLAGHAN Date:March 18 2009 3:18pm
Subject:Re: [style] change proposal: function parameter names in headers
View as plain text  
On Wed, Mar 18, 2009 at 3:16 AM, Konstantin Osipov <kostja@stripped> wrote:
> * Mats Kindahl <mats@stripped> [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:    http://lists.mysql.com/internals?unsub=1
>
>



-- 
Mark Callaghan
mdcallag@stripped
Thread
coding style change proposal: function parameter names in headersIngo Strüwing17 Mar
  • Re: coding style change proposal: function parameter names inheadersSergei Golubchik17 Mar
    • Re: coding style change proposal: function parameter names in headersMARK CALLAGHAN17 Mar
      • Re: coding style change proposal: function parameter names in headersJay Pipes17 Mar
      • [style] change proposal: function parameter names in headersKonstantin Osipov17 Mar
    • Re: coding style change proposal: function parameter names in headersIngo Strüwing17 Mar
      • Re: coding style change proposal: function parameter names inheadersSergei Golubchik17 Mar
  • [style] change proposal: function parameter names in headersKonstantin Osipov17 Mar
    • Re: [style] change proposal: function parameter names in headersIngo Strüwing17 Mar
    • Re: [style] change proposal: function parameter names in headersMats Kindahl18 Mar
      • Re: [style] change proposal: function parameter names in headersKonstantin Osipov18 Mar
        • Re: [style] change proposal: function parameter names in headersMARK CALLAGHAN18 Mar
      • Re: [style] change proposal: function parameter names in headersIngo Strüwing18 Mar
        • Re: [style] change proposal: function parameter names in headersMats Kindahl18 Mar
          • Re: [style] change proposal: function parameter names in headersReggie Burnett23 Mar
        • Re: [style] change proposal: function parameter names in headersMichael Widenius8 Apr