Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/Progmasoft_Core_C_Coding_Guidelines/C11/FORMATTING.md
blob: 5c4dd22944dbc27af755147f15d76805b289d71a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
<!-- SPDX-License-Identifier: CC-BY-4.0 -->

# 2. Formatting

`clang-format` with the profile below does most of the layout. The rules in this chapter are the layout itself; the
profile applies them where `clang-format` 23 can, and [What the tool leaves to you](#what-the-tool-leaves-to-you) lists
the rest.

## The shape of the code

```c
int
CalculateResult(int aFirstValue, int aSecondValue)
{
        if(aFirstValue < 0)
                return (-1);

        return (aFirstValue + aSecondValue);
}

void
NoOperation(void)
{ }
```

## 2.1 Indentation and lines

- **Indent by eight spaces**, never by tabs.
- **Code and comments end by column 100.**
- **A continuation line is indented by eight spaces.**
- **Exactly one blank line between two functions.**

## 2.2 Functions and braces

- **The return type stands on its own line**, above the function name, in declarations and definitions.
- **The opening brace of a function, `struct`, `union`, `enum`, `if`, `for`, `while`, `switch` and `do` stands on its
  own line.**
- **`else` and the `while` of a `do` follow the closing brace**: `} else`, `} else if(`, `} while(`.
- **An empty body is `{ }` on the line after its head**: `NoOperation(void)` above, `for(;;)` then `{ }`, and `do`,
  then `{ } while(condition);`.

## 2.3 Bodies with one statement

- **A body of one statement has no braces**, and the statement stands on the next line. A body of more than one
  statement has braces.
- **The `if` and the `else` of a statement are judged separately**: one may have braces while the other has none.

```c
if(aIsReady)
{
        values[ 0 ] = aValue;
        gsCounter++;
} else if(aValue > 0)
        values[ 1 ] = aValue;
else
        values[ 2 ] = 0;
```

## 2.4 Parentheses and spaces

- **No space between `if`, `for`, `while` or `switch` and its `(`**: `if(`, `else if(`, `switch(state)`.
- **`return` with a value writes it in parentheses, after one space**: `return (result);`, the form
  `clang-format` writes. A `void` function may return early with `return;`.
- **One space after each comma.**
- **Binary arithmetic, bitwise, comparison and assignment operators have a space on each side.** A unary operator (`!`,
  `~`, `+`, `-`, `*`, `&`, `++`, `--`) sticks to its operand.
- **A cast is `(Type) expression`**, with one space; `sizeof` is `sizeof(expression)`. A compound literal has no space
  between `)` and `{`: `(Example_tUserData){ 0 }`.
- **No space around `.` and `->`.**
- **Square brackets have one space inside**, in declarations and in indexing: `values[ 10 ]`, `values[ index ]`.
- **The `*` of a pointer sticks to the type**: `int* pValue`.

## 2.5 Breaking long lines

- **Parameters and arguments that do not fit on one line each get a line of their own**, the first one right after the
  `(` and the others in the column of the first. The closing `)` should stay on the line of the last one.
- **A binary operator that continues an expression starts the new line**: `=`, `+=`, `&&`, `+`, `|`, `==` and the
  others.
- **In a long ternary, `?` and `:` start their lines.**
- **In an expression over several lines, `(` stays on the line of the first operand and `)` on the line of the last.**
  Parentheses are added only where they make the meaning clearer.

```c
Example_List_CopyRange(aInOut_pDestinationList,
                       aIn_pSourceList,
                       aFirstIndex,
                       aCount,
                       aOut_pCopiedCount);

bool isWithinLimits = aIn_pList->count + aAdditionalCount <= EXAMPLE_LIST_MAX_VALUES
        && aIn_pList->capacity <= SIZE_MAX / sizeof(*aIn_pList->pValues);
```

## 2.6 Alignment

Consecutive lines line up, so a block of declarations reads as a table:

- the names and the `=` of declarations in one group, and consecutive assignments, compound ones included;
- the member names of a `struct` or `union`, and the `:` of bit-fields;
- the `=` of enumerators;
- the values of consecutive parameterless macros, and the `\` of a macro over several lines.

```c
typedef struct Example_Header
{
        unsigned int kind  : 4;
        unsigned int flags : 4;
        size_t       size;
} Example_tHeader;
```

## The profile

Copy this file to `.clang-format` at the root of the project. It needs `clang-format` 23; pin one exact version in CI,
because two versions can format the same file differently.

```yaml
---
Language: Cpp
BasedOnStyle: LLVM

IndentWidth: 8
ContinuationIndentWidth: 8
TabWidth: 8
UseTab: Never
ColumnLimit: 100

BreakAfterReturnType: All
BreakBeforeBraces: Custom
BraceWrapping:
  AfterFunction: true
  AfterStruct: true
  AfterUnion: true
  AfterEnum: true
  AfterCaseLabel: true
  AfterControlStatement: Always
  BeforeElse: false
  BeforeWhile: false
  AfterExternBlock: false
  IndentBraces: false
  SplitEmptyFunction: false
  SplitEmptyRecord: false

AllowShortFunctionsOnASingleLine: Empty
AllowShortBlocksOnASingleLine: Empty
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
AllowShortCaseLabelsOnASingleLine: false
SpaceInEmptyBraces: Always

SpaceBeforeParens: Never
SpacesInParens: Never
SpacesInSquareBrackets: true
SpaceBeforeSquareBrackets: false
SpaceAfterCStyleCast: true
SpaceBeforeAssignmentOperators: true
SpaceBeforeCaseColon: false
BitFieldColonSpacing: Both
PointerAlignment: Left
DerivePointerAlignment: false

AlignAfterOpenBracket: true
AlignOperands: DontAlign
BreakBeforeBinaryOperators: All
BreakAfterOpenBracketFunction: false
BreakBeforeCloseBracketFunction: false
AllowAllArgumentsOnNextLine: false
AllowAllParametersOfDeclarationOnNextLine: false
PackArguments:
  BinPack: OnePerLine
PackParameters:
  BinPack: OnePerLine
PenaltyBreakAssignment: 100

AlignConsecutiveAssignments:
  Enabled: true
  AcrossEmptyLines: false
  AcrossComments: false
  AlignCompound: true
  PadOperators: false
  EnumAssignments: true
AlignConsecutiveDeclarations:
  Enabled: true
  AcrossEmptyLines: false
  AcrossComments: false
  AlignFunctionDeclarations: false
AlignConsecutiveBitFields: Consecutive
AlignConsecutiveMacros: Consecutive
AlignEscapedNewlines: Left

IndentCaseLabels: false
IndentCaseBlocks: false
IndentGotoLabels: NoIndent
IndentPPDirectives: AfterHash
PPIndentWidth: 4

Cpp11BracedListStyle: Block
BracedInitializerIndentWidth: 8
EnumTrailingComma: Insert

NumericLiteralCase:
  ExponentLetter: Lower
  HexDigit: Upper
  Prefix: Lower
  Suffix: Upper

SortIncludes:
  Enabled: true
  IgnoreCase: false
IncludeBlocks: Regroup
IncludeIsMainRegex: '$^'
IncludeCategories:
  - Regex: '^<(assert|complex|ctype|errno|fenv|float|inttypes|iso646|limits|locale|math|setjmp|signal|stdalign|stdarg|stdatomic|stdbool|stddef|stdint|stdio|stdlib|stdnoreturn|string|tgmath|threads|time|uchar|wchar|wctype)\.h>$'
    Priority: 1
  - Regex: '^<'
    Priority: 2
  - Regex: '^"'
    Priority: 3

MaxEmptyLinesToKeep: 1
KeepEmptyLines:
  AtStartOfBlock: false
  AtStartOfFile: false
  AtEndOfFile: false
ReflowComments: false
...
```

- `PenaltyBreakAssignment: 100` keeps a call on the line of its `=` and puts one argument on each line when the
  arguments do not fit; with the LLVM default, the formatter breaks before the `=` first.
- `IncludeIsMainRegex: '$^'` stops the formatter from moving a source file's own header to the top: the groups of
  [Files and headers](FILES-AND-HEADERS.md#43-includes) decide the order.
- `EnumTrailingComma: Insert` puts the comma after the last enumerator. LLVM documents that the option can change
  code in ways that need review, so a change it makes is reviewed like any other.

## What the tool leaves to you

`clang-format` 23 cannot express every rule above. These are checked in review, and the formatter's output is
corrected where it differs:

- **Compound literals**: `SpaceAfterCStyleCast` also puts a space before the `{` of a compound literal,
  `(Example_tUserData) { 0 }`.
- **An empty `do` body**: `do`, then `{ } while(condition);` is split into `{` and `} while(condition);`.
- **One statement per body without braces** (2.3), the order of declaration groups and their blank lines, the blank
  lines around `case` groups and `goto` labels, and the columns of `@param` lines.

A part of a file the formatter must not touch may be wrapped in `/* clang-format off */` and `/* clang-format on */`,
as narrowly as the rule needs.