diff options
Diffstat (limited to 'Documentation/CodingGuidelines')
| -rw-r--r-- | Documentation/CodingGuidelines | 37 |
1 files changed, 33 insertions, 4 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index ba047ed224..224f0978a8 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -44,7 +44,7 @@ code are expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). But if you must have a list of rules, here are some language -specific ones. Note that Documentation/ToolsForGit.txt document +specific ones. Note that Documentation/ToolsForGit.adoc document has a collection of tips to help you use some external tools to conform to these guidelines. @@ -298,6 +298,17 @@ For C programs: . since late 2021 with 44ba10d6, we have had variables declared in the for loop "for (int i = 0; i < 10; i++)". + . since late 2023 with 8277dbe987 we have been using the bool type + from <stdbool.h>. + + C99 features we have test balloons for: + + . since late 2024 with v2.48.0-rc0~20, we have test balloons for + compound literal syntax, e.g., (struct foo){ .member = value }; + our hope is that no platforms we care about have trouble using + them, and officially adopt its wider use in mid 2026. Do not add + more use of the syntax until that happens. + New C99 features that we cannot use yet: . %z and %zu as a printf() argument for a size_t (the %z being for @@ -315,6 +326,9 @@ For C programs: encouraged to have a blank line between the end of the declarations and the first statement in the block. + - Do not explicitly initialize global variables to 0 or NULL; + instead, let BSS take care of the zero initialization. + - NULL pointers shall be written as NULL, not as 0. - When declaring pointers, the star sides with the variable @@ -610,8 +624,9 @@ For C programs: - `S_init()` initializes a structure without allocating the structure itself. - - `S_release()` releases a structure's contents without freeing the - structure. + - `S_release()` releases a structure's contents without reinitializing + the structure for immediate reuse, and without freeing the structure + itself. - `S_clear()` is equivalent to `S_release()` followed by `S_init()` such that the structure is directly usable after clearing it. When @@ -755,7 +770,7 @@ Externally Visible Names Writing Documentation: Most (if not all) of the documentation pages are written in the - AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and + AsciiDoc format in *.adoc files (e.g. Documentation/git.adoc), and processed into HTML and manpages (e.g. git.html and git.1 in the same directory). @@ -861,6 +876,9 @@ Markup: _<git-dir>_ _<key-id>_ +Characters are also surrounded by underscores: + _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_ + Git's Asciidoc processor has been tailored to treat backticked text as complex synopsis. When literal and placeholders are mixed, you can use the backtick notation which will take care of correctly typesetting @@ -874,6 +892,17 @@ Markup: As a side effect, backquoted placeholders are correctly typeset, but this style is not recommended. + When documenting multiple related `git config` variables, place them on + a separate line instead of separating them by commas. For example, do + not write this: + `core.var1`, `core.var2`:: + Description common to `core.var1` and `core.var2`. + +Instead write this: + `core.var1`:: + `core.var2`:: + Description common to `core.var1` and `core.var2`. + Synopsis Syntax The synopsis (a paragraph with [synopsis] attribute) is automatically |