diff options
| author | Karthik Nayak <karthik.188@gmail.com> | 2024-10-24 12:53:57 +0200 |
|---|---|---|
| committer | Taylor Blau <me@ttaylorr.com> | 2024-10-24 12:51:30 -0400 |
| commit | be75cec1b62b9f873c7fc50bbaff3002d82ab458 (patch) | |
| tree | 00084fe2cf48a3e4281c65ddf56881fa76cb1b31 | |
| parent | The third batch (diff) | |
| download | git-be75cec1b62b9f873c7fc50bbaff3002d82ab458.tar.gz git-be75cec1b62b9f873c7fc50bbaff3002d82ab458.zip | |
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>
| -rw-r--r-- | Documentation/CodingGuidelines | 14 |
1 files changed, 14 insertions, 0 deletions
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. |