Junio C Hamano <gitster@xxxxxxxxx> writes: > Linus Arver <linusa@xxxxxxxxxx> 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. This sounds like a good rule to me. > "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. Thanks for the illuminating examples. Agreed. > Are there functions declared in strvec.h you have in mind that their > parameters are confusing and hard to guess what they mean? TBH I only learned recently (while writing the patch in this thread) that parameter names in prototypes were optional. I got a little confused initially when looking at strvec.h for the first time because none of the parameters were named. Having thought a bit more about these functions, none of them have repeated types like in your example where naming is warranted, so I think they're fine as is. OTOH if we were treating these .h files as something meant for direct external consumption (that is, if strvec.h is libified and external users outside of Git are expected to use it directly as their first point of documentation), at that point it might make sense to name the parameters (akin to the style of manpages for syscalls). But I imagine at that point we would have some other means of developer docs (beyond raw header files) for libified parts of Git, so even in that case it's probably fine to keep things as is. Thanks.
