[PATCH v2 4/5] Documentation: document idiomatic function names
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Jul 30, 2024, 07:24 UTC
- Message-ID
- <d4ce00303f230e6ebc7099e07bb451811e6eabab.1722323818.git.ps@pks.im>
- In-Reply-To
- <cover.1722323818.git.ps@pks.im>
We semi-regularly have discussions around whether a function shall be named `S_release()`, `S_clear()` or `S_free()`. Indeed, it may not be obvious which of these is preferable as we never really defined what each of these variants means exactly.
Carve out a space where we can add idiomatic names for common functions in our coding guidelines and define each of those functions. Like this, we can get to a shared understanding of their respective semantics and can easily point towards our style guide in future discussions such that our codebase becomes more consistent over time.
Note that the intent is not to rename all functions which violate these semantics right away. Rather, the intent is to slowly converge towards a common style over time.
Signed-off-by: Patrick Steinhardt <ps@pks.im> --- Documentation/CodingGuidelines | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a6a1ede204..b63a8f9a44 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -560,6 +560,23 @@ For C programs: void reset_strbuf(struct strbuf *buf); + - There are several common idiomatic names for functions performing + specific tasks on a structure `S`: + + - `S_init()` initializes a structure without allocating the + structure itself. + + - `S_release()` releases a structure's contents without freeing the + structure. + + - `S_clear()` is equivalent to `S_release()` followed by `S_init()` + such that the structure is directly usable after clearing it. When + `S_clear()` is provided, `S_init()` shall not allocate resources + that need to be released again. + + - `S_free()` releases a structure's contents and frees the + structure. + For Perl programs: - Most of the C guidelines above apply.
-- 2.46.0.dirty