-----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-----
