Re: [PATCH] strvec: use correct member name in comments

[Junio C Hamano <gitster@pobox.com>]

Linus Arver <linusa@google.com> writes:

> Side note: should we start naming the parameters in strvec.h? I would
> think that it wouldn't hurt at this point (as the API is pretty stable).
> If you think that's worth it, I could reroll to include that in this
> series (and also improve my commit message for this patch).

I am not sure if it adds more value to outweigh the cost of
churning.  When the meaning of the parameters are obvious only by
looking at their types, a prototype without parameter names is
easier to maintain, by allowing the parameters to be renamed only
once in the implementation.  When the meaning of parameters are not
obvious from their types, we do want them to be named so that you
only have to refer to the header files to know the argument order.

"void *calloc(size_t, size_t)" would not tell us if we should pass
the size of individual element or the number of elements first, and
writing "void *calloc(size_t nmemb, size_t size)" to make it more
obvious is a good idea.

On the other hand, "void *realloc(void *, size_t)" is sufficient to
tell us that we are passing a pointer as the first parameter and the
desired size as the second parameter, without them having any name.

Are there functions declared in strvec.h you have in mind that their
parameters are confusing and hard to guess what they mean?  

Thanks.