Re: [PATCH v2 12/12] refs: move the remaining ref module declarations to refs.h

From: Michael Haggerty <mhagger@alum.mit.edu>
Date: Jun 20, 2015, 01:53 UTC
Message-ID: <5584C789.7020209@alum.mit.edu>
In-Reply-To: <20150615183504.GB4041@peff.net>

On 06/15/2015 08:35 PM, Jeff King wrote:

Show 21 quoted lines

> On Mon, Jun 15, 2015 at 11:13:22AM -0700, Junio C Hamano wrote:
> 
>>> @@ -78,15 +170,15 @@ typedef int each_ref_fn(const char *refname,
>>>   * modifies the reference also returns a nonzero value to immediately
>>>   * stop the iteration.
>>>   */
>>> -extern int head_ref(each_ref_fn, void *);
>>> +extern int head_ref(each_ref_fn fn, void *cb_data);
>>
>> For example, between these two, what did we gain?
>>
>> Because of their types, it already was clear what the two parameters
>> are in the original, without noisewords like "fn" (which obviously
>> stands for a "function", but that is clear due to "each_ref_fn").
> 
> I think the real benefit of naming parameters is that you can talk about
> "fn" and "cb_data" by name in the docstring[1]. Of course we do not do
> that here, so we could clearly wait until "if-and-when" we do so. But I
> do not think it is a big deal for our style guide to say "we always name
> parameters in declarations", and to bring things in line there (though
> perhaps it should be a separate patch in that case).

I also like the idea that all parameters in declarations should be named. It is true that sometimes the purpose of a parameter is easy to guess from its type without a name. But giving them names make them easier to talk about in docstrings, in commit messages, or even on the mailing list when reviewing patches or discussing bugs.

Moreover, I don't see the value of wasting mental energy wondering "hmmm, in this case is the meaning sufficiently obvious from the type?" every time I write a function declaration. It is easier to have a consistent policy of putting them in.

Finally, when I'm inventing new functions (which I admit isn't the case here), I usually write the declaration first and then copy-paste it to the C file as the first step in writing the definition. If I name the parameters in the declaration then (a) I don't have to go back and edit them at the definition and (b) if parameter names are needed later at the declaration (e.g., for a docstring), I don't have to edit the declaration again, cross-referencing back to the C file to make sure I name them consistently.

I will split the "add names in declarations" changes into a separate patch. Also, that way Junio can ignore the patch if he still disagrees :-)

Show 11 quoted lines

>>> -extern int for_each_glob_ref_in(each_ref_fn, const char *pattern, const char* prefix, void *);
>>> +extern int for_each_glob_ref_in(each_ref_fn fn, const char *pattern, const char* prefix, void *cb_data);
>>
>> Likewise for addition of fn and cb_data.
>>
>> If you really want to make unrelated changes to this file, what you
>> should fix is to update "const char* prefix" to "const char *prefix"
>> ;-)
> 
> IMHO they are in the same boat (style fixes), and I would be happy to
> see both improved. :)

I will fix this too.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu