# [PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names 3 messages from 2024-10-24 to 2024-10-24. Participants: Karthik Nayak, karthik nayak, Taylor Blau. Thread: https://gitlist.dev/t/62403 ## Karthik Nayak, 2024-10-24 10:53 Subject: [PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names Message-ID: <20241024105357.2605168-1-karthik.188@gmail.com> URL: https://gitlist.dev/e/20241024105357.2605168-1-karthik.188%40gmail.com In-Reply-To: ``` We often name functions with arbitrary suffixes like `_1` as an extension of another existing function. This creates confusion and doesn't provide good clarity into the functions purpose. Let's document good function naming etiquette in our CodingGuidelines. Signed-off-by: Karthik Nayak --- I decided to send in a third version based on the feedback received from Justin and Junio, this version is bit less aggressive and more hopeful. Documentation/CodingGuidelines | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 30fda4142c..87904791cb 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -621,6 +621,20 @@ For C programs: - `S_free()` releases a structure's contents and frees the structure. + - Function names should be clear and descriptive, accurately reflecting + their purpose or behavior. Arbitrary suffixes that do not add meaningful + context can lead to confusion, particularly for newcomers to the codebase. + + Historically, the '_1' suffix has been used in situations where: + + - A function handles one element among a group that requires similar + processing. + - A recursive function has been separated from its setup phase. + + The '_1' suffix can be used as a concise way to indicate these specific + cases. However, it is recommended to find a more descriptive name wherever + possible to improve the readability and maintainability of the code. + For Perl programs: - Most of the C guidelines above apply. Range-diff against v2: 1: dd556a8029 ! 1: 617b8831d3 CodingGuidelines: discourage arbitrary suffixes in function names @@ Documentation/CodingGuidelines: 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. ++ - Function names should be clear and descriptive, accurately reflecting ++ their purpose or behavior. Arbitrary suffixes that do not add meaningful ++ context can lead to confusion, particularly for newcomers to the codebase. + -+ The '_1' suffix for function names has historically indicated: ++ Historically, the '_1' suffix has been used in situations where: + -+ - functions processing one of several elements that all need to be -+ handled similarly. ++ - A function handles one element among a group that requires similar ++ processing. ++ - A recursive function has been separated from its setup phase. + -+ - recursive functions that need to be separated from a setup stage. -+ -+ To maintain clarity and avoid confusion, such arbitrary suffixes are -+ discouraged, as they provide no meaningful insight into the function's -+ role. -+ -+To maintain clarity and avoid confusion, -+ arbitrary suffixes such as _1 are discouraged, as they provide no -+ meaningful insight into the function's role. ++ The '_1' suffix can be used as a concise way to indicate these specific ++ cases. However, it is recommended to find a more descriptive name wherever ++ possible to improve the readability and maintainability of the code. + For Perl programs: -- 2.47.0 ``` ## karthik nayak, 2024-10-24 11:02 Subject: Re: [PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names Message-ID: URL: https://gitlist.dev/e/CAOLa%3DZTJoUCMJhnak-tRpftN%2B3Txuz-B1_%2BpF6s8xtZ2BP3A5g%40mail.gmail.com In-Reply-To: <20241024105357.2605168-1-karthik.188@gmail.com> ``` Karthik Nayak writes: > We often name functions with arbitrary suffixes like `_1` as an > extension of another existing function. This creates confusion and > doesn't provide good clarity into the functions purpose. Let's document > good function naming etiquette in our CodingGuidelines. > I replied to the wrong ID, the previous versions can be found here: https://lore.kernel.org/git/20241021124145.636561-1-karthik.188@gmail.com/#t ``` ## Taylor Blau, 2024-10-24 16:50 Subject: Re: [PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names Message-ID: URL: https://gitlist.dev/e/Zxp67zpIsxAe15gN%40nand.local In-Reply-To: <20241024105357.2605168-1-karthik.188@gmail.com> ``` On Thu, Oct 24, 2024 at 12:53:57PM +0200, Karthik Nayak wrote: > We often name functions with arbitrary suffixes like `_1` as an > extension of another existing function. This creates confusion and > doesn't provide good clarity into the functions purpose. Let's document > good function naming etiquette in our CodingGuidelines. > > Signed-off-by: Karthik Nayak > --- Thanks, I think that this version is looking quite good. Let's let it simmer a little longer so folks can continue to discuss, but I think that this is looking quite good. Thanks, Taylor ```