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

[Patrick Steinhardt <ps@pks.im>]

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