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

> 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.
>