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

From: Jeff King <peff@peff.net>
Date: Jun 15, 2015, 18:35 UTC
Message-ID: <20150615183504.GB4041@peff.net>
In-Reply-To: <xmqqfv5salh9.fsf@gitster.dls.corp.google.com>

On Mon, Jun 15, 2015 at 11:13:22AM -0700, Junio C Hamano wrote:

Show 12 quoted lines

> > @@ -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).

[1] For instance, in the docstring here, which is just outside the
    context, we use the awkward phrase "the specified callback
    function". That would be much simpler as just `fn`, though having so
    few parameters to these functions, it is fairly clear already.

Show 8 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. :)

-Peff