| Message ID | 20240828040049.GF3999193@coredump.intra.peff.net (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | a219a6739cc14b52a7ba08170eebe9cf11505667 |
| Headers | show |
| Series | unused parameters: the final countdown | expand |
On Wed, Aug 28, 2024 at 12:01 AM Jeff King <peff@peff.net> wrote: > Having now removed or annotated all of the unused function parameters in > our code base, I found that each instance falls into one of three > categories: > > 1. ignoring the parameter is a bug (e.g., a function takes a ptr/len > pair, but ignores the length). Detecting these helps us find the > bugs. > > 2. the parameter is unnecessary (and usually left over from a > refactoring or earlier iteration of a patches series). Removing > these cleans up the code. > > 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?
On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote: > On Wed, Aug 28, 2024 at 12:01 AM Jeff King <peff@peff.net> wrote: > > Having now removed or annotated all of the unused function parameters in > > our code base, I found that each instance falls into one of three > > categories: > > > > 1. ignoring the parameter is a bug (e.g., a function takes a ptr/len > > pair, but ignores the length). Detecting these helps us find the > > bugs. > > > > 2. the parameter is unnecessary (and usually left over from a > > refactoring or earlier iteration of a patches series). Removing > > these cleans up the code. > > > > 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? Updating our coding guidelines would certainly be welcome. Other than that this series looks good to me and is a step into the right direction in my opinion. Thanks! Patrick
Eric Sunshine <sunshine@sunshineco.com> writes: >> 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.
diff --git a/config.mak.dev b/config.mak.dev index 5229c35484..50026d1e0e 100644 --- a/config.mak.dev +++ b/config.mak.dev @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),) DEVELOPER_CFLAGS += -Wno-empty-body DEVELOPER_CFLAGS += -Wno-missing-field-initializers DEVELOPER_CFLAGS += -Wno-sign-compare -DEVELOPER_CFLAGS += -Wno-unused-parameter endif endif
Having now removed or annotated all of the unused function parameters in our code base, I found that each instance falls into one of three categories: 1. ignoring the parameter is a bug (e.g., a function takes a ptr/len pair, but ignores the length). Detecting these helps us find the bugs. 2. the parameter is unnecessary (and usually left over from a refactoring or earlier iteration of a patches series). Removing these cleans up the code. 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). Certainly instances of (3) are more common than (1), but after finding all of these, I think there were enough cases of (1) that it justifies the work in annotating all of the (3)s. 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> --- config.mak.dev | 1 - 1 file changed, 1 deletion(-)