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

[Taylor Blau <me@ttaylorr.com>]

On Tue, Oct 22, 2024 at 03:45:38AM -0500, karthik nayak wrote:
> >> 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.
>
> The crux here is that this meaning is internalized by people who know
> the code through in and out. But for anyone new to the project, this is
> not evident from the naming.

Right. I think that with that in mind, a good goal might be to document
that convention to make sure that newcomers to the project can easily
interpret what foo() and foo_1() mean. Another approach is the one you
pursue here, which is to change the existing convention in the name of
making the code more approachable for newcomers.

Both approaches meet the same end, but the former does not involve
changing existing conventions, but instead documenting them. That seems
like a more reasonable path to me.

> > 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.
> >
>
> I get the usecase of having such functions. I totally see the need, it's
> mostly the naming that I'm trying to change.
>
> Let's consider two of such functions:
>
> 1. mark_remote_island_1: This function is called to do _some_ work on a
> single remote island when iterating over a list.
> 2. find_longest_prefixes_1: This is a recursive function which is used
> to find the longest prefix.
>
> If you notice, both use the "_1" suffix and do different things (operate
> on a single instance from a list vs provide recursive behavior). So the
> user has to read the code to understand, which makes the "_1" a bit
> confusing.
>
> Second, this could have instead been named:
> 1. mark_single_remote_island: Which reads better, giving the idea that
> we are really working on a single remote island. Whereas having a "_1"
> doesn't easily imply the same.
> 2. find_longest_prefixes_recursively: Which also reads better, and gives
> a hint on how the function operates and why it is split out from the
> base function.

I don't disagree that writing "single" or "recursively" can be
considered clearer. I think that the convention to suffix such functions
with "_1()" is more terse, but saves characters and can avoid awkward
line wrapping.

Thanks,
Taylor