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

From: Junio C Hamano <[email-masked]>
Date: Wed, 23 Oct 2024 17:50:17 -0700

Taylor Blau <[email-masked]> writes:

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

I am reasonably sure that I was the first user of the _1()
convention, or at least I was one of them.  The reason for the
choice of suffix was only because there wasn't anything suitable
when refactoring an existing function foo() into a set-up part and
its recursive body, so I just kept the set-up part and the single
call into the new function in the original foo(), and had to give a
name to the new function that holds the body of the original logic
that was moved from foo().

Neither foo_helper() or foo_recursive() were descriptive enough to
warrant such longer suffixes than a simple _1().  They easily can
get "help by doing what?" and "recursively doing what?" reaction,
which is a sure sign that the suffixes are not descriptive enough.

That was the only reason why I picked that "short-and-sweet but
cryptic" suffix.

Surely all of _1(), _helper(), _recursive() are meaningless.  If we
were to replace existing uses of them, the replacement has to be 10x
better.

Having said all that, as an aspirational goal, I think it is good to
encourage people to find a name that is descriptive when writing a
new function.  I'd refrain from judging if it is way too obvious to
be worth documenting (as I am officially on vacation and shouldn't
be thinking too much about the project).

Thanks.