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

[Taylor Blau <me@ttaylorr.com>]

On Mon, Oct 21, 2024 at 02:59:00PM +0200, Patrick Steinhardt wrote:
> 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