Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 28, 2024, 15:17 UTC
Message-ID: <xmqqle0g4qxp.fsf@gitster.g>
In-Reply-To: <CAPig+cQLr+vAzkt8UJNVCeE8osGEcEfFunG36oqxa0k8JamJzQ@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 25 quoted lines

>>   3. the function has to conform to a specific interface (because it's
>>      used via a function pointer, or matches something on the other side
>>      of an #ifdef). These ones are annoying, but annotating them with
>>      UNUSED is not too bad (especially if the compiler tells you about
>>      the problem promptly).
>> [...]
>> And since the code base is now at a spot where we compile cleanly with
>> -Wunused-parameter, turning it on will make it the responsibility of
>> individual patch writers going forward.
>>
>> Signed-off-by: Jeff King <peff@peff.net>
>> ---
>> diff --git a/config.mak.dev b/config.mak.dev
>> @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
>>  DEVELOPER_CFLAGS += -Wno-sign-compare
>> -DEVELOPER_CFLAGS += -Wno-unused-parameter
>
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?

I am not yet convinced 100%, but probably it is a good idea.

We have our idioms and conventions like use of UNLEAK(), UNUSED, __attribute__ to annotate varargs functions that take printf-like format, always using "{ 0 }" and no other form to zero-initialize an auto variable of an aggregate type, etc., that are unreasonable for somebody, who is new to the project but is fluent in and competent at C, to know all of them.

For things like UNLEAK() that require a bit more than general competence in the language, a bit more thought and peeking the implementation to understand how they work, we should document them to make it easier to learn for new people.

Consistently using "{ 0 }", instead of picking a single random member and initialize the aggrevate with "{ .it = 0 }", is asking the writer to pick between two _valid_ C language constructs and always use one of them, so it may make sense to document it, even though the general "do what the existing code does" may be sufficient.

Unlike them, UNUSED smells a lot more obvious, and because the code base is full of API functions that take callback functions, we have plenty of existing uses of it for those who are competent but are unfamiliar to the code base to notice and pick up quickly.

So I have a feeling that relatively speaking it is less necessary to help new contributors with documenting UNUSED than other conventions we have.

I have no objection if somebody else does a thoughtful job to document these things evenly, but if we are going to document UNUSED, we should explicitly document that it is our policy to document each and every one of these conventions to help new contributors.

Thanks.