On Mon, Oct 21, 2024 at 02:59:00PM +0200, Patrick Steinhardt wrote: > 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. I am not sure here... I think that using a "_1()" suffix means that the function is processing one of a number of elements that all need to be handled similarly, but where both the processing of an individual element, and the handling of a group of elements are both complicated enough to be placed in their own function. It's also a helpful convention when you have a recursive function that does some setup during its initial call, but subsequent layers of recursion don't need or want to repeat that setup. So I'm not sure I agree that "_1()" is always a bad idea as this changes suggests (i.e. by writing that "they provide no meaningful insight into the function's role"). Perhaps we could rephrase what is written here to suggest a couple of instances where we wouldn't want to apply this rule, and the two that I have written above could perhaps be a useful starting point. But I lean more towards not adjusting our CodingGuidelines at all here. Thanks, Taylor
