List:Internals« Previous MessageNext Message »
From:Jay Pipes Date:March 17 2009 3:30pm
Subject:Re: coding style change proposal: function parameter names in headers
View as plain text  
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

MARK CALLAGHAN wrote:
> On Tue, Mar 17, 2009 at 5:46 AM, Sergei Golubchik <serg@stripped> wrote:
>> Hi, Ingo!
>>
>> On Mar 17, Ingo Strüwing wrote:
>>> I propose to demand function parameter names in header files.
>>>
>>> We do not document functions in header files. The documentation goes to
>>> the C/C++ file where it is defined.
>>> With parameter names in header files, one would not need to look up the
>>> source file for every function call.
>>>
>>> Example:
>>>
>>>   Restore_info* prepare_for_restore(String*, LEX_STRING,
>>>                                     const char*, bool,
>>>                                     const char*);
>>>
>>> This declaration forces me to look into kernel.cc whenever I want to
>>> call it.
>>>
>>>   Restore_info* prepare_for_restore(String *backupdir,
>>>                                     LEX_STRING orig_dir,
>>>                                     const char *query,
>>>                                     bool with_compression,
>>>                                     const char *comment);
>>>
>>> In this case there is a good chance that I do not need to consult the
>>> function comment in the source file.
>> And why would you prefer to consult the header file, and not the source
>> file ?
> 
> Comments in the header file describe the interface. Comments in the
> source file provide more detail on the implementation. The interface
> should be less likely to change over time.
> 
> Speaking for those new to the code, I frequently don't know what I am
> looking for when browsing. Browsing the header file is much more
> efficient than browsing many more and larger source files. Of course,
> this is mostly moot for me now as I use 5.0.37 and there are almost no
> comments in the header files (mysql_priv.h for example).

+5.

>> I like it the way it is (and actually remove argument names from the
>> prototype declarations sometimes) because that's how it works with
>> ctags - any function definition is only one keypress away when one uses
>> tags. But because tag file uses regular expressions to find a function,
>> for example, /^Restore_info* prepare_for_restore(String *backupdir,/,
>> it is not able to distinguish between the prototype
>>
>> Restore_info* prepare_for_restore(String *backupdir,
>>                                  LEX_STRING orig_dir,
>>                                  const char *query,
>>                                  bool with_compression,
>>                                  const char *comment);
>>
>> in the beginning of the file, and the function itself
>>
>> Restore_info* prepare_for_restore(String *backupdir,
>>                                  LEX_STRING orig_dir,
>>                                  const char *query,
>>                                  bool with_compression,
>>                                  const char *comment)
>> {
>>
>> in the middle of the file.
>> That's why I like it when prototypes are written without argument names.
>> Of course, this argument only applies to prototypes in the source files,
>> not in the headers. But it's nice to use the same style everywhere.
>>
>> Regards / Mit vielen Grüßen,
>> Sergei
>>
>> --
>>   __  ___     ___ ____  __
>>  /  |/  /_ __/ __/ __ \/ /   Sergei Golubchik <serg@stripped>
>>  / /|_/ / // /\ \/ /_/ / /__  Principal Software Engineer/Server Architect
>> /_/  /_/\_, /___/\___\_\___/  Sun Microsystems GmbH, HRB München 161028
>>       <___/                  Sonnenallee 1, 85551 Kirchheim-Heimstetten
>> Geschäftsführer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
>> Vorsitzender des Aufsichtsrates: Martin Häring
>>
>> --
>> MySQL Internals Mailing List
>> For list archives: http://lists.mysql.com/internals
>> To unsubscribe:    http://lists.mysql.com/internals?unsub=1
>>
>>
> 
> 
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkm/wh8ACgkQ2upbWsB4UtGOLACfWlMGdi7qmKjj43TRsQNbgsA/
eecAoI12swZGNqcexb4lm4td39tP8uAr
=p1K3
-----END PGP SIGNATURE-----
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