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