Patrick Steinhardt <ps@xxxxxx> writes: > 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. > I agree, going the other way doesn't help either. > 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 I tried to keep the wording to also not just say "it is not allowed to use such suffixes", but mostly to discourage it. I guess we can also iterate on this as needed with time. Karthik
Attachment:
signature.asc
Description: PGP signature
