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

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