| Message ID | 20241024105357.2605168-1-karthik.188@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | be75cec1b62b9f873c7fc50bbaff3002d82ab458 |
| Headers | show |
| Series | [v3] CodingGuidelines: discourage arbitrary suffixes in function names | expand |
Karthik Nayak <karthik.188@gmail.com> 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
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 <karthik.188@gmail.com> > --- 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
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.
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 <karthik.188@gmail.com> --- 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(+) 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: