Skip to content

Commit be75cec

Browse files
KarthikNayakttaylorr
authored andcommitted
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 <[email protected]> Signed-off-by: Taylor Blau <[email protected]>
1 parent 34b6ce9 commit be75cec

File tree

1 file changed

+14
-0
lines changed

1 file changed

+14
-0
lines changed

Documentation/CodingGuidelines

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -621,6 +621,20 @@ For C programs:
621621
- `S_free()` releases a structure's contents and frees the
622622
structure.
623623

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+
624638
For Perl programs:
625639

626640
- Most of the C guidelines above apply.

0 commit comments

Comments
 (0)