git/Documentation/CodingGuidelines, branch v2.47.2

CodingGuidelines: also mention MAYBE_UNUSED

2024-08-29T18:28:07Z

A function that uses a parameter in one build may lose all uses of the parameter in another build, depending on the configuration. A workaround for such a case, MAYBE_UNUSED, should also be mentioned when we recommend the use of UNUSED to our developers. Keep the addition to the guideline short and document the criteria to choose between UNUSED and MAYBE_UNUSED near their definition. Signed-off-by: Junio C Hamano

CodingGuidelines: mention -Wunused-parameter and UNUSED

2024-08-28T16:51:25Z

Now that -Wunused-parameter is on by default for DEVELOPER=1 builds, people may trigger it, blocking their build. When it's a mistake for the parameter to exist, the path forward is obvious: remove it. But sometimes you need to suppress the warning, and the "UNUSED" mechanism for that is specific to our project, so people may not know about it. Let's put some advice in CodingGuidelines, including an example warning message. That should help people who grep for the warning text after seeing it from the compiler. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'jc/coding-style-c-operator-with-spaces'

2024-08-26T18:32:24Z

Write down whitespacing rules around C opeators. * jc/coding-style-c-operator-with-spaces: CodingGuidelines: spaces around C operators

CodingGuidelines: spaces around C operators

2024-08-20T21:10:10Z

As we have operated with "write like how your surrounding code is written" for too long, after a huge code drop from another project, we'll end up being inconsistent before such an imported code is cleaned up. We have many uses of cast operator with a space before its operand, mostly in the reftable code. Spell the convention out before it spreads to other places. Signed-off-by: Junio C Hamano

Merge branch 'jc/document-use-of-local'

2024-08-14T21:54:58Z

Doc update. * jc/document-use-of-local: doc: note that AT&T ksh does not work with our test suite

Merge branch 'ps/doc-more-c-coding-guidelines'

2024-08-08T17:41:20Z

Some project conventions have been added to CodingGuidelines. * ps/doc-more-c-coding-guidelines: Documentation: consistently use spaces inside initializers Documentation: document idiomatic function names Documentation: document naming schema for structs and their functions Documentation: clarify indentation style for C preprocessor directives clang-format: fix indentation width for preprocessor directives

Documentation: consistently use spaces inside initializers

2024-07-30T20:50:25Z

Our coding guide is inconsistent with how it uses spaces inside of initializers (`struct foo bar = { something }`). While we mostly carry the space between open and closing braces and the initialized members, in one case we don't. Fix this one instance such that we consistently carry the space. This is also consistent with how clang-format formats such initializers. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

Documentation: document idiomatic function names

2024-07-30T20:50:25Z

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 Signed-off-by: Junio C Hamano

Documentation: document naming schema for structs and their functions

2024-07-30T20:50:25Z

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: clarify indentation style for C preprocessor directives

2024-07-30T20:50:25Z

In the preceding commit, we have settled on using a single space per nesting level to indent preprocessor directives. Clarify our coding guidelines accordingly. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano