From 541204aabea80ce466b5f62bf6613cdaf104dd5a Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Tue, 30 Jul 2024 09:24:43 +0200 Subject: [PATCH] Documentation: document naming schema for structs and their functions We nowadays have a proper mishmash of struct-related functions that are called `_` (e.g. `clear_prio_queue()`) versus functions that are called `_` (e.g. `strbuf_clear()`). While the former style may be easier to tie into a spoken conversation, most of our communication happens in text anyway. Furthermore, prefixing functions with the name of the structure they operate on makes it way easier to group them together, see which functions are related, and will also help folks who are using code completion. Let's thus settle on one style, namely the one where functions start with the name of the structure they operate on. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 65fba3b810..a6a1ede204 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -541,6 +541,25 @@ For C programs: use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + - The primary data structure that a subsystem 'S' deals with is called + `struct S`. Functions that operate on `struct S` are named + `S_()` and should generally receive a pointer to `struct S` as + first parameter. E.g. + + struct strbuf; + + void strbuf_add(struct strbuf *buf, ...); + + void strbuf_reset(struct strbuf *buf); + + is preferred over: + + struct strbuf; + + void add_string(struct strbuf *buf, ...); + + void reset_strbuf(struct strbuf *buf); + For Perl programs: - Most of the C guidelines above apply. -- 2.47.3