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@xxxxxxxxx>
---
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
