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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 24, 2024, 00:50 UTC
Message-ID: <xmqqr086pbna.fsf@gitster.g>
In-Reply-To: <ZxfVwQxMlcJbGt5D@nand.local>

Taylor Blau <me@ttaylorr.com> 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.