Documentation: document idiomatic function names

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Patrick Steinhardt committed Jul 30, 2024 at 09:24 UTC 10f0723c8df41c9c2a4dec7e3571e98ec57138f1
1 file changed +17
Documentation/CodingGuidelines
+17
@@ -560,6 +560,23 @@ For C programs:
560
561 void reset_strbuf(struct strbuf *buf);
562
563 + - There are several common idiomatic names for functions performing
564 + specific tasks on a structure `S`:
565 +
566 + - `S_init()` initializes a structure without allocating the
567 + structure itself.
568 +
569 + - `S_release()` releases a structure's contents without freeing the
570 + structure.
571 +
572 + - `S_clear()` is equivalent to `S_release()` followed by `S_init()`
573 + such that the structure is directly usable after clearing it. When
574 + `S_clear()` is provided, `S_init()` shall not allocate resources
575 + that need to be released again.
576 +
577 + - `S_free()` releases a structure's contents and frees the
578 + structure.
579 +
580 For Perl programs:
581
582 - Most of the C guidelines above apply.