gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/05-spacing.md

Spacing Options

← Prev: Indentation | Back to Index | Next: Includes →

Navigation: Alignment | Breaking | Braces | Indentation | Spacing | Includes | Languages | Comments | Advanced

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:

void f() {
  if(true) {
    f();
  }
}

ControlStatements:

void f() {
  if (true) {
    f();
  }
}

Always:

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:

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:

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:

t f( Deleted & ) & = delete;

false:

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:

int a[ 5 ];

false:

int a[5];

SpaceBeforeSquareBrackets

Add spaces before [.

Type: Boolean

Example:

true:

int a [5];
int a [5][5];

false:

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:

static_cast< int >(arg);
std::vector< int > vec;

Operators and Assignments

SpaceBeforeAssignmentOperators

Add space before assignment operators.

Type: Boolean Default: true

Example:

true:

int a = 5;
a += 42;

false:

int a= 5;
a+= 42;

SpaceBeforeRangeBasedForLoopColon

Add space before colon in range-based for loop.

Type: Boolean Default: true

Example:

true:

for (auto v : values) {}

false:

for (auto v: values) {}

SpaceInEmptyBlock

Deprecated: Use Block in SpaceInEmptyBraces.

Add space in empty blocks.

Type: Boolean

Example:

true:

void f() { }
while (true) { }

false:

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:

void f() { }
class Unit { };
auto a = [] { };
int x{ };

Block:

void f() { }
class Unit { };
auto a = [] { };
int x{};

Never:

void f() {}
class Unit {};
auto a = [] {};
int x{};

Casts and Templates

SpaceAfterCStyleCast

Add space after C-style cast.

Type: Boolean

Example:

true:

(int) i;

false:

(int)i;

SpaceAfterLogicalNot

Add space after logical not operator (!).

Type: Boolean

Example:

true:

! someExpression();

false:

!someExpression();

SpaceAfterTemplateKeyword

Add space after template keyword.

Type: Boolean Default: true

Example:

true:

template <int> void foo();

false:

template<int> void foo();

SpaceBeforeCaseColon

Add space before case colon.

Type: Boolean

Example:

true:

switch (x) {
  case 1 : break;
}

false:

switch (x) {
  case 1: break;
}

SpaceBeforeCpp11BracedList

Add space before C++11 braced list.

Type: Boolean

Example:

true:

Foo foo { bar };
Foo {};
vector<int> { 1, 2, 3 };
new int[3] { 1, 2, 3 };

false:

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:

Foo::Foo() : a(a) {}

false:

Foo::Foo(): a(a) {}

SpaceBeforeInheritanceColon

Add space before inheritance colon.

Type: Boolean Default: true

Example:

true:

class Foo : Bar {}

false:

class Foo: Bar {}

SpaceBeforeJsonColon

Add space before JSON colon.

Type: Boolean

Example:

true:

{
  "key" : "value"
}

false:

{
  "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:

void f() {
  if (true) {
    f();  // comment
  }       // comment
}

SpacesInContainerLiterals

Add spaces in container literals.

Type: Boolean

Example:

true (JavaScript/JSON):

var arr = [1, 2, 3];
obj = { a: 1, b: 2, c: 3 };

false:

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):

//A comment
// A comment
//  A comment

SpaceAroundPointerQualifiers

Configure spaces around pointer qualifiers.

Type: SpaceAroundPointerQualifiersStyle Values:

• Default, Before, After, Both

Examples:

Default:

void* const* x = NULL;

Before:

void *const *x = NULL;

After:

void* const* x = NULL;

Both:

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:

unsigned bf : 2;

None:

unsigned bf:2;

Before:

unsigned bf :2;

After:

unsigned bf: 2;

Empty Lines

MaxEmptyLinesToKeep

Maximum consecutive empty lines to keep.

Type: Unsigned Default: 1

Example:

1:

int f() {
  int = 1;

  return i;
}

2:

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:

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:

void f() {
  foo();
}

true:

void f() {

  foo();
}

KeepEmptyLinesAtEOF

Deprecated: Use AtEndOfFile in KeepEmptyLines.

Keep empty lines at end of file.

Type: Boolean

Common Patterns

Minimal Spacing (Compact)

SpaceBeforeParens: Never
SpaceBeforeAssignmentOperators: true
SpaceInEmptyBraces: Never
SpacesInParens: Never
SpacesInSquareBrackets: false
SpacesInAngles: Never
SpaceAfterCStyleCast: false
SpaceAfterLogicalNot: false
SpacesBeforeTrailingComments: 1
MaxEmptyLinesToKeep: 1

Standard Spacing

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)

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 - Align code elements
• Indentation - Control indentation
• Breaking - Control line breaks
• Full Style Options Reference

---

← Prev: Indentation | Back to Index | Next: Includes →