From: MARK CALLAGHAN
Date: March 17 2009 1:22pm
Subject: Re: coding style change proposal: function parameter names in headers
List-Archive: http://lists.mysql.com/internals/36410
Message-Id: <f0661f8c0903170622u22bc45der2502f585e5e3685d@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Tue, Mar 17, 2009 at 5:46 AM, Sergei Golubchik <serg@stripped> wrote:
> Hi, Ingo!
>
> On Mar 17, Ingo Str=FCwing 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:
>>
>> =A0 Restore_info* prepare_for_restore(String*, LEX_STRING,
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =
const char*, bool,
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =
const char*);
>>
>> This declaration forces me to look into kernel.cc whenever I want to
>> call it.
>>
>> =A0 Restore_info* prepare_for_restore(String *backupdir,
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =
LEX_STRING orig_dir,
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =
const char *query,
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =
bool with_compression,
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =
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).

>
> 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,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0LEX_ST=
RING orig_dir,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0const =
char *query,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0bool w=
ith_compression,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0const =
char *comment);
>
> in the beginning of the file, and the function itself
>
> Restore_info* prepare_for_restore(String *backupdir,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0LEX_ST=
RING orig_dir,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0const =
char *query,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0bool w=
ith_compression,
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0const =
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=FC=DFen,
> Sergei
>
> --
> =A0 __ =A0___ =A0 =A0 ___ ____ =A0__
> =A0/ =A0|/ =A0/_ __/ __/ __ \/ / =A0 Sergei Golubchik <serg@stripped>
> =A0/ /|_/ / // /\ \/ /_/ / /__ =A0Principal Software Engineer/Server Arch=
itect
> /_/ =A0/_/\_, /___/\___\_\___/ =A0Sun Microsystems GmbH, HRB M=FCnchen 16=
1028
> =A0 =A0 =A0 <___/ =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0Sonnenallee 1, 85551=
 Kirchheim-Heimstetten
> Gesch=E4ftsf=FChrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
> Vorsitzender des Aufsichtsrates: Martin H=E4ring
>
> --
> 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