[PATCH] CodingGuidelines: discourage arbitrary suffixes in function names

From: Karthik Nayak <karthik.188@gmail.com>
Date: Oct 21, 2024, 12:41 UTC
Message-ID: <20241021124145.636561-1-karthik.188@gmail.com>

We often name functions with arbitrary suffixes like `_1` as an extension of another existing function. This created 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>
---

This is mostly in response to an ongoing thread [1] where I ran into one of these functions and it really took me a while to wrap my head around what the function does.

[1]: https://lore.kernel.org/git/CAOLa=ZREg3xuaT6mbM8+Havn3regZDhK45kGy0+Fw8t56c7Mpg@mail.gmail.com/#R

 Documentation/CodingGuidelines | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 30fda4142c..b8e2d30567 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -621,6 +621,11 @@ 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. 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.

-- 
2.47.0