{"thread":{"id":"62403","subject":"[PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names","startedAt":"2024-10-24T10:54:02Z","lastAt":"2024-10-24T16:50:58Z","messageCount":3,"participants":["Karthik Nayak","karthik nayak","Taylor Blau"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"506010","messageId":"20241024105357.2605168-1-karthik.188@gmail.com","threadId":"62403","inReplyTo":"https://lore.kernel.org/r/20241021124145.636561-1-karthik.188@gmail.com","subject":"[PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-10-24T10:53:57Z","receivedAt":"2024-10-24T10:54:02Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"We often name functions with arbitrary suffixes like `_1` as an\nextension of another existing function. This creates confusion and\ndoesn't provide good clarity into the functions purpose. Let's document\ngood function naming etiquette in our CodingGuidelines.\n\nSigned-off-by: Karthik Nayak \n---\n\nI decided to send in a third version based on the feedback received from\nJustin and Junio, this version is bit less aggressive and more hopeful.\n\n Documentation/CodingGuidelines | 14 ++++++++++++++\n 1 file changed, 14 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 30fda4142c..87904791cb 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -621,6 +621,20 @@ For C programs:\n - `S_free()` releases a structure's contents and frees the\n structure.\n \n+ - Function names should be clear and descriptive, accurately reflecting\n+ their purpose or behavior. Arbitrary suffixes that do not add meaningful\n+ context can lead to confusion, particularly for newcomers to the codebase.\n+\n+ Historically, the '_1' suffix has been used in situations where:\n+\n+ - A function handles one element among a group that requires similar\n+ processing.\n+ - A recursive function has been separated from its setup phase.\n+\n+ The '_1' suffix can be used as a concise way to indicate these specific\n+ cases. However, it is recommended to find a more descriptive name wherever\n+ possible to improve the readability and maintainability of the code.\n+\n For Perl programs:\n \n - Most of the C guidelines above apply.\n\nRange-diff against v2:\n1: dd556a8029 ! 1: 617b8831d3 CodingGuidelines: discourage arbitrary suffixes in function names\n @@ Documentation/CodingGuidelines: For C programs:\n - `S_free()` releases a structure's contents and frees the\n structure.\n \n -+ - Function names should be self-explanatory, clearly reflecting their\n -+ purpose or behavior.\n ++ - Function names should be clear and descriptive, accurately reflecting\n ++ their purpose or behavior. Arbitrary suffixes that do not add meaningful\n ++ context can lead to confusion, particularly for newcomers to the codebase.\n +\n -+ The '_1' suffix for function names has historically indicated:\n ++ Historically, the '_1' suffix has been used in situations where:\n +\n -+ - functions processing one of several elements that all need to be\n -+ handled similarly.\n ++ - A function handles one element among a group that requires similar\n ++ processing.\n ++ - A recursive function has been separated from its setup phase.\n +\n -+ - recursive functions that need to be separated from a setup stage.\n -+\n -+ To maintain clarity and avoid confusion, such arbitrary suffixes are\n -+ discouraged, as they provide no meaningful insight into the function's\n -+ role.\n -+\n -+To maintain clarity and avoid confusion,\n -+ arbitrary suffixes such as _1 are discouraged, as they provide no\n -+ meaningful insight into the function's role.\n ++ The '_1' suffix can be used as a concise way to indicate these specific\n ++ cases. However, it is recommended to find a more descriptive name wherever\n ++ possible to improve the readability and maintainability of the code.\n +\n For Perl programs:\n \n-- \n2.47.0\n\n"},{"id":"506011","messageId":"CAOLa=ZTJoUCMJhnak-tRpftN+3Txuz-B1_+pF6s8xtZ2BP3A5g@mail.gmail.com","threadId":"62403","inReplyTo":"20241024105357.2605168-1-karthik.188@gmail.com","subject":"Re: [PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names","fromName":"karthik nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-10-24T11:02:15Z","receivedAt":"2024-10-24T11:02:18Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Karthik Nayak writes:\n\n> We often name functions with arbitrary suffixes like `_1` as an\n> extension of another existing function. This creates confusion and\n> doesn't provide good clarity into the functions purpose. Let's document\n> good function naming etiquette in our CodingGuidelines.\n>\n\nI replied to the wrong ID, the previous versions can be found here:\nhttps://lore.kernel.org/git/20241021124145.636561-1-karthik.188@gmail.com/#t\n"},{"id":"506051","messageId":"Zxp67zpIsxAe15gN@nand.local","threadId":"62403","inReplyTo":"20241024105357.2605168-1-karthik.188@gmail.com","subject":"Re: [PATCH v3] CodingGuidelines: discourage arbitrary suffixes in function names","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-24T16:50:55Z","receivedAt":"2024-10-24T16:50:58Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Thu, Oct 24, 2024 at 12:53:57PM +0200, Karthik Nayak wrote:\n> We often name functions with arbitrary suffixes like `_1` as an\n> extension of another existing function. This creates confusion and\n> doesn't provide good clarity into the functions purpose. Let's document\n> good function naming etiquette in our CodingGuidelines.\n>\n> Signed-off-by: Karthik Nayak \n> ---\n\nThanks, I think that this version is looking quite good. Let's let it\nsimmer a little longer so folks can continue to discuss, but I think\nthat this is looking quite good.\n\nThanks,\nTaylor\n"}]}