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

From: Karthik Nayak <karthik.188@gmail.com>
Date: Oct 24, 2024, 10:53 UTC
Message-ID: <20241024105357.2605168-1-karthik.188@gmail.com>
In-Reply-To: <https://lore.kernel.org/r/20241021124145.636561-1-karthik.188@gmail.com>

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(+)

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