CodingGuidelines: discourage arbitrary suffixes in function names
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> Signed-off-by: Taylor Blau <me@ttaylorr.com>
Karthik Nayak committed
Oct 24, 2024 at 12:53 UTC
be75cec1b62b9f873c7fc50bbaff3002d82ab458
1 file changed
+14
Documentation/CodingGuidelines
+14
@@ -621,6 +621,20 @@ For C programs:
621
- `S_free()` releases a structure's contents and frees the
622
structure.
623
624
+ - Function names should be clear and descriptive, accurately reflecting
625
+ their purpose or behavior. Arbitrary suffixes that do not add meaningful
626
+ context can lead to confusion, particularly for newcomers to the codebase.
627
+
628
+ Historically, the '_1' suffix has been used in situations where:
629
+
630
+ - A function handles one element among a group that requires similar
631
+ processing.
632
+ - A recursive function has been separated from its setup phase.
633
+
634
+ The '_1' suffix can be used as a concise way to indicate these specific
635
+ cases. However, it is recommended to find a more descriptive name wherever
636
+ possible to improve the readability and maintainability of the code.
637
+
638
For Perl programs:
639
640
- Most of the C guidelines above apply.