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

From

Karthik Nayak <karthik.188@gmail.com>

Date

Oct 23, 2024, 07:57 UTC

Message-ID

<20241023075706.1393147-1-karthik.188@gmail.com>

In-Reply-To

<20241021124145.636561-1-karthik.188@gmail.com>

Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
---
 Documentation/CodingGuidelines | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 30fda4142c..635d6f3a27 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -621,6 +621,24 @@ 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.
+
+   The '_1' suffix for function names has historically indicated:
+
+    - functions processing one of several elements that all need to be
+      handled similarly.
+
+    - 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.
+
 For Perl programs:
 
  - Most of the C guidelines above apply.

Range-diff against v1:
1:  0acdf6902c ! 1:  dd556a8029 CodingGuidelines: discourage arbitrary suffixes in function names
    @@ Commit message
         CodingGuidelines: discourage arbitrary suffixes in function names
     
         We often name functions with arbitrary suffixes like `_1` as an
    -    extension of another existing function. This created confusion and
    +    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.
     
    @@ Documentation/CodingGuidelines: For C programs:
            structure.
      
     + - Function names should be self-explanatory, clearly reflecting their
    -+   purpose or behavior. To maintain clarity and avoid confusion,
    ++   purpose or behavior.
    ++
    ++   The '_1' suffix for function names has historically indicated:
    ++
    ++    - functions processing one of several elements that all need to be
    ++      handled similarly.
    ++
    ++    - 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.
     +

-- 
2.47.0