We semi-regularly have discussions around whether a function shall be
named `release()` or `free()`. For most of the part we use these two
terminologies quite consistently though:
- `release()` only frees internal state of a structure, whereas the
structure itself is not free'd.
- `free()` frees both internal state and the structure itself.
Carve out a space where we can add idiomatic names for common functions
in our coding guidelines. This space can get extended in the future when
we feel the need to document more idiomatic names.
Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
---
Documentation/CodingGuidelines | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 34fcbcb5a4..ace4c4ad0c 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -560,6 +560,18 @@ For C programs:
void reset_strbuf(struct strbuf *buf);
+ - There are several common idiomatic names for functions performing
+ specific tasks on structures:
+
+ - `<struct>_init()` initializes a structure without allocating the
+ structure itself.
+
+ - `<struct>_release()` releases a structure's contents without
+ freeing the structure.
+
+ - `<struct>_free()` releases a structure's contents and frees the
+ structure.
+
For Perl programs:
- Most of the C guidelines above apply.
--
2.46.0.rc1.dirty
Attachment:
signature.asc
Description: PGP signature
