zhongwei/gh-jamie-bitflight-claude-skills-development-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:49:58 +08:00
commit 5007abf04b
89 changed files with 44129 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

797
skills/clang-format/references/05-spacing.md Normal file
View File

@@ -0,0 +1,797 @@
# Spacing Options
[← Prev: Indentation](04-indentation.md) | [Back to Index](index.md) | [Next: Includes →](06-includes.md)
**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md)
Fine-tune whitespace placement throughout your code.
## Parentheses and Brackets
### SpaceBeforeParens
Add space before opening parentheses.
**Type:** `SpaceBeforeParensStyle` **Values:**
- `Never` - **Deprecated.** Use `Custom` with all `SpaceBeforeParensOptions` except `AfterPlacementOperator` set to `false`
- `ControlStatements` - Only before control statement parens
- `ControlStatementsExceptControlMacros` - Control statements except macros
- `NonEmptyParentheses` - Only if parentheses aren't empty
- `Always` - Always add space
- `Custom` - Use `SpaceBeforeParensOptions`
**Examples:**
`Never`:
```cpp
void f() {
if(true) {
f();
}
}
```
`ControlStatements`:
```cpp
void f() {
if (true) {
f();
}
}
```
`Always`:
```cpp
void f () {
if (true) {
f ();
}
}
```
### SpaceBeforeParensOptions
Fine-grained control when `SpaceBeforeParens: Custom`.
**Sub-options:**
- `AfterControlStatements` (bool) - Space between control statement keywords and opening parentheses
- `AfterForeachMacros` (bool) - Space between foreach macros and opening parentheses
- `AfterFunctionDeclarationName` (bool) - Space between function declaration name and opening parentheses
- `AfterFunctionDefinitionName` (bool) - Space between function definition name and opening parentheses
- `AfterIfMacros` (bool) - Space between if macros and opening parentheses
- `AfterOverloadedOperator` (bool) - Space between operator overloading and opening parentheses
- `AfterPlacementOperator` (bool) - Space between operator `new`/`delete` and opening parentheses
- `AfterRequiresInClause` (bool) - Space between requires keyword in requires clause and opening parentheses
- `AfterRequiresInExpression` (bool) - Space between requires keyword in requires expression and opening parentheses
- `BeforeNonEmptyParentheses` (bool) - Space before opening parentheses only if not empty
### SpacesInParens
Defines in which cases spaces will be inserted after `(` and before `)`.
**Type:** `SpacesInParensStyle` **Values:**
- `Never` - Never put a space in parentheses
- `Custom` - Use `SpacesInParensOptions`
**Example:**
`Never`:
```cpp
void f() {
if(true) {
f();
}
}
```
### SpacesInParensOptions
Control of individual spaces in parentheses when `SpacesInParens: Custom`.
**Sub-options:**
- `ExceptDoubleParentheses` (bool) - Override other options to prevent space when both opening and closing use multiple parentheses
- `InConditionalStatements` (bool) - Space in parentheses inside conditional statements
- `InCStyleCasts` (bool) - Space in C style casts
- `InEmptyParentheses` (bool) - Space in empty parentheses, i.e. `()`
- `Other` (bool) - Space in parentheses not covered by preceding options
**Example:**
```yaml
SpacesInParens: Custom
SpacesInParensOptions:
InConditionalStatements: true
Other: true
```
### SpacesInParentheses
**Deprecated:** Use `SpacesInParens` with `Custom` and set all `SpacesInParensOptions` to `true` except `InCStyleCasts` and `InEmptyParentheses`.
Add spaces inside parentheses.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
t f( Deleted & ) & = delete;
```
`false`:
```cpp
t f(Deleted &) & = delete;
```
### SpaceInEmptyParentheses
**Deprecated:** Use `InEmptyParentheses` in `SpacesInParensOptions`.
### SpacesInCStyleCastParentheses
**Deprecated:** Use `InCStyleCasts` in `SpacesInParensOptions`.
### SpacesInConditionalStatement
**Deprecated:** Use `InConditionalStatements` in `SpacesInParensOptions`.
### SpacesInSquareBrackets
Add spaces inside square brackets.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
int a[ 5 ];
```
`false`:
```cpp
int a[5];
```
### SpaceBeforeSquareBrackets
Add spaces before `[`.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
int a [5];
int a [5][5];
```
`false`:
```cpp
int a[5];
int a[5][5];
```
**Note:** Lambdas will not be affected. Only the first `[` gets a space.
### SpacesInAngles
Add spaces inside angle brackets.
**Type:** `SpacesInAnglesStyle` **Values:**
- `Never` - Remove spaces after `<` and before `>`
- `Always` - Add spaces after `<` and before `>`
- `Leave` - Keep a single space if any were present
**Example:**
`Always`:
```cpp
static_cast< int >(arg);
std::vector< int > vec;
```
## Operators and Assignments
### SpaceBeforeAssignmentOperators
Add space before assignment operators.
**Type:** `Boolean` **Default:** `true`
**Example:**
`true`:
```cpp
int a = 5;
a += 42;
```
`false`:
```cpp
int a= 5;
a+= 42;
```
### SpaceBeforeRangeBasedForLoopColon
Add space before colon in range-based for loop.
**Type:** `Boolean` **Default:** `true`
**Example:**
`true`:
```cpp
for (auto v : values) {}
```
`false`:
```cpp
for (auto v: values) {}
```
### SpaceInEmptyBlock
**Deprecated:** Use `Block` in `SpaceInEmptyBraces`.
Add space in empty blocks.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
void f() { }
while (true) { }
```
`false`:
```cpp
void f() {}
while (true) {}
```
### SpaceInEmptyBraces
Specifies when to insert a space in empty braces.
**Type:** `SpaceInEmptyBracesStyle` **Values:**
- `Always` - Always insert a space in empty braces
- `Block` - Only insert a space in empty blocks
- `Never` - Never insert a space in empty braces
**Note:** This option doesn't apply to initializer braces if `Cpp11BracedListStyle` is not `Block`.
**Examples:**
`Always`:
```cpp
void f() { }
class Unit { };
auto a = [] { };
int x{ };
```
`Block`:
```cpp
void f() { }
class Unit { };
auto a = [] { };
int x{};
```
`Never`:
```cpp
void f() {}
class Unit {};
auto a = [] {};
int x{};
```
## Casts and Templates
### SpaceAfterCStyleCast
Add space after C-style cast.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
(int) i;
```
`false`:
```cpp
(int)i;
```
### SpaceAfterLogicalNot
Add space after logical not operator (!).
**Type:** `Boolean`
**Example:**
`true`:
```cpp
! someExpression();
```
`false`:
```cpp
!someExpression();
```
### SpaceAfterTemplateKeyword
Add space after template keyword.
**Type:** `Boolean` **Default:** `true`
**Example:**
`true`:
```cpp
template <int> void foo();
```
`false`:
```cpp
template<int> void foo();
```
### SpaceBeforeCaseColon
Add space before case colon.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
switch (x) {
case 1 : break;
}
```
`false`:
```cpp
switch (x) {
case 1: break;
}
```
### SpaceBeforeCpp11BracedList
Add space before C++11 braced list.
**Type:** `Boolean`
**Example:**
`true`:
```cpp
Foo foo { bar };
Foo {};
vector<int> { 1, 2, 3 };
new int[3] { 1, 2, 3 };
```
`false`:
```cpp
Foo foo{ bar };
Foo{};
vector<int>{ 1, 2, 3 };
new int[3]{ 1, 2, 3 };
```
### SpaceBeforeCtorInitializerColon
Add space before constructor initializer colon.
**Type:** `Boolean` **Default:** `true`
**Example:**
`true`:
```cpp
Foo::Foo() : a(a) {}
```
`false`:
```cpp
Foo::Foo(): a(a) {}
```
### SpaceBeforeInheritanceColon
Add space before inheritance colon.
**Type:** `Boolean` **Default:** `true`
**Example:**
`true`:
```cpp
class Foo : Bar {}
```
`false`:
```cpp
class Foo: Bar {}
```
### SpaceBeforeJsonColon
Add space before JSON colon.
**Type:** `Boolean`
**Example:**
`true`:
```javascript
{
"key" : "value"
}
```
`false`:
```javascript
{
"key": "value"
}
```
**Note:** For other languages like JavaScript, use `SpacesInContainerLiterals` instead.
## Containers and Comments
### SpacesBeforeTrailingComments
Number of spaces before trailing comments.
**Type:** `Unsigned` **Default:** `1`
**Example:**
`2`:
```cpp
void f() {
if (true) {
f(); // comment
} // comment
}
```
### SpacesInContainerLiterals
Add spaces in container literals.
**Type:** `Boolean`
**Example:**
`true` (JavaScript/JSON):
```javascript
var arr = [1, 2, 3];
obj = { a: 1, b: 2, c: 3 };
```
`false`:
```javascript
var arr = [1, 2, 3];
obj = { a: 1, b: 2, c: 3 };
```
**Note:** For JSON, use `SpaceBeforeJsonColon` instead.
### SpacesInLineCommentPrefix
Spaces in line comment prefix.
**Type:** `SpacesInLineComment` **Sub-options:**
- `Minimum` - Minimum spaces
- `Maximum` - Maximum spaces (use `-1` for no max)
**Example:**
`Minimum: 1, Maximum: -1` (no max):
```cpp
//A comment
// A comment
// A comment
```
### SpaceAroundPointerQualifiers
Configure spaces around pointer qualifiers.
**Type:** `SpaceAroundPointerQualifiersStyle` **Values:**
- `Default`, `Before`, `After`, `Both`
**Examples:**
`Default`:
```cpp
void* const* x = NULL;
```
`Before`:
```cpp
void *const *x = NULL;
```
`After`:
```cpp
void* const* x = NULL;
```
`Both`:
```cpp
void * const * x = NULL;
```
## Bit Fields
### BitFieldColonSpacing
Spacing around bit field colon.
**Type:** `BitFieldColonSpacingStyle` **Values:**
- `Both` - Add spaces on both sides
- `None` - No spaces
- `Before` - Space before only
- `After` - Space after only
**Examples:**
`Both`:
```cpp
unsigned bf : 2;
```
`None`:
```cpp
unsigned bf:2;
```
`Before`:
```cpp
unsigned bf :2;
```
`After`:
```cpp
unsigned bf: 2;
```
## Empty Lines
### MaxEmptyLinesToKeep
Maximum consecutive empty lines to keep.
**Type:** `Unsigned` **Default:** `1`
**Example:**
`1`:
```cpp
int f() {
int = 1;
return i;
}
```
`2`:
```cpp
int f() {
int i = 1;
return i;
}
```
### KeepEmptyLines
Which empty lines are kept.
**Type:** `KeepEmptyLinesStyle` **Sub-options:**
- `AtEndOfFile` (bool) - Keep empty lines at end of file
- `AtStartOfBlock` (bool) - Keep empty lines at start of blocks
- `AtStartOfFile` (bool) - Keep empty lines at start of file
**Note:** `MaxEmptyLinesToKeep` determines how many consecutive empty lines are kept.
**Example:**
```yaml
KeepEmptyLines:
AtEndOfFile: false
AtStartOfBlock: false
AtStartOfFile: false
```
### KeepEmptyLinesAtTheStartOfBlocks
**Deprecated:** Use `AtStartOfBlock` in `KeepEmptyLines`.
Keep empty lines at start of blocks.
**Type:** `Boolean` **Default:** `true`
**Example:**
`false`:
```cpp
void f() {
foo();
}
```
`true`:
```cpp
void f() {
foo();
}
```
### KeepEmptyLinesAtEOF
**Deprecated:** Use `AtEndOfFile` in `KeepEmptyLines`.
Keep empty lines at end of file.
**Type:** `Boolean`
## Common Patterns
### Minimal Spacing (Compact)
```yaml
SpaceBeforeParens: Never
SpaceBeforeAssignmentOperators: true
SpaceInEmptyBraces: Never
SpacesInParens: Never
SpacesInSquareBrackets: false
SpacesInAngles: Never
SpaceAfterCStyleCast: false
SpaceAfterLogicalNot: false
SpacesBeforeTrailingComments: 1
MaxEmptyLinesToKeep: 1
```
### Standard Spacing
```yaml
SpaceBeforeParens: ControlStatements
SpaceBeforeAssignmentOperators: true
SpaceInEmptyBraces: Never
SpacesInParens: Never
SpacesInSquareBrackets: false
SpacesInAngles: Never
SpaceAfterCStyleCast: false
SpaceAfterLogicalNot: false
SpaceAfterTemplateKeyword: true
SpaceBeforeCpp11BracedList: false
SpacesBeforeTrailingComments: 2
MaxEmptyLinesToKeep: 1
KeepEmptyLines:
AtStartOfBlock: false
```
### Generous Spacing (Readable)
```yaml
SpaceBeforeParens: ControlStatements
SpaceBeforeAssignmentOperators: true
SpaceInEmptyBraces: Always
SpacesInParens: Never
SpacesInSquareBrackets: false
SpacesInAngles: Never
SpaceAfterCStyleCast: true
SpaceAfterLogicalNot: true
SpaceAfterTemplateKeyword: true
SpaceBeforeCpp11BracedList: true
SpacesBeforeTrailingComments: 2
MaxEmptyLinesToKeep: 2
KeepEmptyLines:
AtStartOfBlock: true
```
## Tips
1. **Consistency**: Apply spacing rules uniformly across the codebase
2. **Readability**: More spaces can improve readability but increase line length
3. **Language Conventions**: Some languages have strong spacing conventions
4. **Trailing Comments**: Use at least 2 spaces before trailing comments for clarity
5. **Empty Lines**: Limit `MaxEmptyLinesToKeep` to prevent excessive whitespace
6. **Containers**: Enable `SpacesInContainerLiterals` for JSON/JavaScript readability
7. **Deprecations**: Prefer newer options like `SpacesInParens` over deprecated `SpacesInParentheses`
8. **Custom Control**: Use `Custom` settings with fine-grained options for precise control
## See Also
- [Alignment](01-alignment.md) - Align code elements
- [Indentation](04-indentation.md) - Control indentation
- [Breaking](02-breaking.md) - Control line breaks
- [Full Style Options Reference](complete/clang-format-style-options.md)
---
[← Prev: Indentation](04-indentation.md) | [Back to Index](index.md) | [Next: Includes →](06-includes.md)