Re: [PATCH] CodingGuidelines: discourage arbitrary suffixes in function names

From: Taylor Blau <me@ttaylorr.com>
Date: Oct 21, 2024, 20:02 UTC
Message-ID: <ZxazVG65+W0qKLXh@nand.local>
In-Reply-To: <ZxZP01C-9RngukZy@pks.im>

On Mon, Oct 21, 2024 at 02:59:00PM +0200, Patrick Steinhardt wrote:

Show 35 quoted lines

> On Mon, Oct 21, 2024 at 02:41:45PM +0200, Karthik Nayak wrote:
> > We often name functions with arbitrary suffixes like `_1` as an
> > extension of another existing function. This created confusion and
>
> Micro-nit: s/created/creates/
>
> [snip]
> > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> > index 30fda4142c..b8e2d30567 100644
> > --- a/Documentation/CodingGuidelines
> > +++ b/Documentation/CodingGuidelines
> > @@ -621,6 +621,11 @@ For C programs:
> >      - `S_free()` releases a structure's contents and frees the
> >        structure.
> >
> > + - Function names should be self-explanatory, clearly reflecting their
> > +   purpose or behavior. To maintain clarity and avoid confusion,
> > +   arbitrary suffixes such as _1 are discouraged, as they provide no
> > +   meaningful insight into the function's role.
>
> Names being self-explanatory is certainly a worthwhile goal, even though
> I guess that it's a bit more on the idealized side of things. Functions
> will often not be fully self-explanatory, which is likely just a matter
> of reality. I mostly just don't want us to end on the other side of the
> spectrum where we go militant on "Every function must be no longer than
> 2 lines of code such that it can be self-explanatory".
>
> And yes, I'm of course stretching what you are saying quite a bit, I
> know that this is not what you want to say. I'm merely writing down my
> own thoughts while thinking it through.
>
> So, that being said, I agree that we shouldn't use arbitrary suffixes,
> as these are quite hard to understand indeed and typically don't really
> provide any context. So as long as we interpret this rule leniently I'm
> happy with it.

I am not sure here... I think that using a "_1()" suffix means that the function is processing one of a number of elements that all need to be handled similarly, but where both the processing of an individual element, and the handling of a group of elements are both complicated enough to be placed in their own function.

It's also a helpful convention when you have a recursive function that does some setup during its initial call, but subsequent layers of recursion don't need or want to repeat that setup.

So I'm not sure I agree that "_1()" is always a bad idea as this changes suggests (i.e. by writing that "they provide no meaningful insight into the function's role").

Perhaps we could rephrase what is written here to suggest a couple of instances where we wouldn't want to apply this rule, and the two that I have written above could perhaps be a useful starting point. But I lean more towards not adjusting our CodingGuidelines at all here.

Thanks, Taylor