gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/02-breaking.md

Breaking & Line Wrapping Options

← Prev: Alignment | Back to Index | Next: Braces →

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

Control where lines break and how code wraps when it exceeds column limits.

Overview

Breaking options determine where and how clang-format inserts line breaks. These options work together with ColumnLimit to control code width and readability.

Column Limit

ColumnLimit

Maximum line length before wrapping.

Type: Unsigned Default: 80

ColumnLimit: 100  # 100 characters per line
ColumnLimit: 0    # No limit

Example:

// ColumnLimit: 80
void function(int param1,
              int param2,
              int param3);

// ColumnLimit: 120
void function(int param1, int param2, int param3);

Allow Short Constructs on Single Line

These options control when short code blocks can remain on one line.

AllowShortBlocksOnASingleLine

Type: ShortBlockStyle Values:

• Never - Never merge blocks into single line
• Empty - Only merge empty blocks
• Always - Always merge short blocks

Examples:

Never:

while (true) {
}
while (true) {
  continue;
}

Empty:

while (true) {}
while (true) {
  continue;
}

Always:

while (true) {}
while (true) { continue; }

AllowShortCaseLabelsOnASingleLine

Keep short case labels on a single line.

Type: Boolean

Example:

true:

switch (a) {
case 1: x = 1; break;
case 2: return;
}

false:

switch (a) {
case 1:
  x = 1;
  break;
case 2:
  return;
}

AllowShortEnumsOnASingleLine

Keep short enums on a single line.

Type: Boolean

Example:

true:

enum { A, B } myEnum;

enum class Color { Red, Green, Blue };

false:

enum {
  A,
  B
} myEnum;

enum class Color {
  Red,
  Green,
  Blue
};

AllowShortFunctionsOnASingleLine

Type: ShortFunctionStyle Values:

• None - Never merge functions
• InlineOnly - Only merge functions defined inside a class
• Empty - Only merge empty functions
• Inline - Merge inline and functions defined in class
• All - Merge all functions

Examples:

InlineOnly:

class Foo {
  void f() { foo(); }
};
void f() {
  foo();
}

Empty:

void f() {}
void f2() {
  bar();
}

All:

class Foo {
  void f() { foo(); }
};
void f() { bar(); }

AllowShortIfStatementsOnASingleLine

Type: ShortIfStyle Values:

• Never - Never put short ifs on one line
• WithoutElse - Only if without else
• OnlyFirstIf - Only first if without else
• AllIfsAndElse - All short if/else on one line

Examples:

Never:

if (a)
  return;

if (b)
  return;
else
  return;

WithoutElse:

if (a) return;

if (b)
  return;
else
  return;

AllIfsAndElse:

if (a) return;

if (b) return;
else return;

AllowShortLambdasOnASingleLine

Type: ShortLambdaStyle Values:

• None - Never merge lambdas
• Empty - Only empty lambdas
• Inline - Lambdas inside function calls
• All - All lambdas

Examples:

None:

auto lambda = []() {
  return 1;
};

Empty:

auto lambda = []() {};
auto lambda2 = []() {
  return 1;
};

All:

auto lambda = []() { return 1; };

AllowShortLoopsOnASingleLine

Keep short loops on a single line.

Type: Boolean

Example:

true:

while (true) continue;
for (int i = 0; i < 10; ++i) {}

false:

while (true)
  continue;
for (int i = 0; i < 10; ++i) {
}

Breaking Before/After Elements

BreakBeforeBinaryOperators

Where to wrap binary operators.

Type: BinaryOperatorStyle Values:

• None - Break after operators
• NonAssignment - Break before non-assignment operators
• All - Break before all binary operators

Examples:

None:

LooooooooooongType loooooooooooooooooooooongVariable =
    someLooooooooooooooooongFunction();

bool value = aaaaaaaaaaaaaaaaaaaaa +
                 aaaaaaaaaaaaaaaaaaa ==
             aaaaaaaaaaaaaaaaaaaaaaa &&

NonAssignment:

LooooooooooongType loooooooooooooooooooooongVariable =
    someLooooooooooooooooongFunction();

bool value = aaaaaaaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaaaaa
                 == aaaaaaaaaaaaaaaaaaaaaaa
             && aaaaaaaaaaaaaaaaaaaaaaaa;

All:

LooooooooooongType loooooooooooooooooooooongVariable
    = someLooooooooooooooooongFunction();

bool value = aaaaaaaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaaaaa
                 == aaaaaaaaaaaaaaaaaaaaaaa
             && aaaaaaaaaaaaaaaaaaaaaaaa;

BreakBeforeTernaryOperators

Break before ternary operators.

Type: Boolean

Examples:

true:

veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
    ? firstValue
    : secondValue;

false:

veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
    firstValue :
    secondValue;

BreakBinaryOperations

Type: BreakBinaryOperationsStyle Since: clang-format 20

The break binary operations style to use.

Values:

• Never - Don't break binary operations
• OnePerLine - Binary operations will either be all on same line, or each operation will have one line each
• RespectPrecedence - Binary operations of a particular precedence that exceed the column limit will have one line each

Examples:

Never:

aaa + bbbb * ccccc - ddddd +
eeeeeeeeeeeeeeee;

OnePerLine:

aaa +
bbbb *
ccccc -
ddddd +
eeeeeeeeeeeeeeee;

RespectPrecedence:

aaa +
bbbb * ccccc -
ddddd +
eeeeeeeeeeeeeeee;

BreakConstructorInitializers

Break constructor initializers.

Type: BreakConstructorInitializersStyle Values:

• BeforeColon - Break before : and ,
• BeforeComma - Break before ,
• AfterColon - Break after :

Examples:

BeforeColon:

Constructor()
    : initializer1()
    , initializer2()

BeforeComma:

Constructor()
    : initializer1(),
      initializer2()

AfterColon:

Constructor() :
    initializer1(),
    initializer2()

BreakInheritanceList

Break inheritance list.

Type: BreakInheritanceListStyle Values:

• BeforeColon - Break before :
• BeforeComma - Break before ,
• AfterColon - Break after :
• AfterComma - Break after ,

Examples:

BeforeColon:

class Foo
    : Base1
    , Base2
{};

AfterColon:

class Foo :
    Base1,
    Base2
{};

BreakStringLiterals

Allow breaking string literals.

Type: Boolean

Example:

true:

const char* x = "veryVeryVeryVeryVeryVe"
                "ryVeryVeryVeryVeryVery"
                "VeryLongString";

false (exceeds column limit):

const char* x = "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";

BreakAdjacentStringLiterals

Break adjacent string literals.

Type: Boolean Default: true

Example:

true:

return "Code" "Llama";

false:

return "CodeLlama";

Breaking Templates and Return Types

BreakAfterReturnType

Control breaking after return types.

Type: ReturnTypeBreakingStyle Values:

• None - Automatic
• All - Always break after return type
• TopLevel - Break after top-level function return types
• AllDefinitions - Break after all definition return types
• TopLevelDefinitions - Break after top-level definition return types

Examples:

None:

class A {
  int f() { return 0; }
};
int f();
int f() { return 1; }

All:

class A {
  int
  f() {
    return 0;
  }
};
int
f();
int
f() {
  return 1;
}

TopLevel:

class A {
  int f() { return 0; }
};
int
f();
int
f() {
  return 1;
}

BreakTemplateDeclarations

Breaking around template declarations.

Type: BreakTemplateDeclarationsStyle Values:

• No - Don't force breaks
• MultiLine - Break multi-line template declarations
• Yes - Always break after template declaration

Examples:

No:

template <typename T> T foo() {
}
template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
                              int bbbbbbbbbbbbbbbbbbbbb) {
}

MultiLine:

template <typename T> T foo() {
}
template <typename T>
T foo(int aaaaaaaaaaaaaaaaaaaaa,
      int bbbbbbbbbbbbbbbbbbbbb) {
}

Yes:

template <typename T>
T foo() {
}
template <typename T>
T foo(int aaaaaaaaaaaaaaaaaaaaa,
      int bbbbbbbbbbbbbbbbbbbbb) {
}

BreakAfterAttributes

Break after attributes.

Type: AttributeBreakingStyle Values:

• Always - Always break after attributes
• Leave - Leave as is
• Never - Never break after attributes

Example:

Always:

[[nodiscard]]
int f();

[[gnu::const]] [[nodiscard]]
int g();

Never:

[[nodiscard]] int f();

[[gnu::const]] [[nodiscard]] int g();

Special Breaking Options

BreakBeforeConceptDeclarations

Break before C++20 concept declarations.

Type: BreakBeforeConceptDeclarationsStyle Values:

• Never - Keep on same line
• Allowed - Break if needed
• Always - Always break

Example:

Always:

template <typename T>
concept ...

Never:

template <typename T> concept ...

BreakBeforeTemplateCloser

Type: Boolean Since: clang-format 21

If true, break before a template closing bracket (>) when there is a line break after the matching opening bracket (<).

Examples:

true:

template <typename Foo, typename Bar>

template <typename Foo,
          typename Bar>

template <
    typename Foo,
    typename Bar
>

false:

template <typename Foo, typename Bar>

template <typename Foo,
          typename Bar>

template <
    typename Foo,
    typename Bar>

BreakBeforeInlineASMColon

Break before inline ASM colon.

Type: BreakBeforeInlineASMColonStyle Values:

• Never, OnlyMultiline, Always

BreakFunctionDefinitionParameters

Break function definition parameters.

Type: Boolean

Example:

true:

void functionDeclaration(int A, int B);

void functionDefinition(
    int A,
    int B
) {
  // function body
}

Parameter and Argument Control

AllowAllArgumentsOnNextLine

Allow putting all arguments on the next line.

Type: Boolean

Example:

true:

callFunction(
    a, b, c, d);

false (will try to fit some on same line):

callFunction(a,
             b, c, d);

AllowAllParametersOfDeclarationOnNextLine

Allow all parameters of declaration on next line.

Type: Boolean

Similar to AllowAllArgumentsOnNextLine but for declarations.

AllowBreakBeforeQtProperty

Type: Boolean Since: clang-format 22

Allow breaking before Q_Property keywords READ, WRITE, etc. as if they were preceded by a comma. This allows them to be formatted according to BinPackParameters.

BinPackArguments

Pack function arguments together.

Type: Boolean

Example:

true:

void f() {
  f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
}

false:

void f() {
  f(aaaaaaaaaaaaaaaaaaaa,
    aaaaaaaaaaaaaaaaaaaa,
    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
}

BinPackLongBracedList

Type: Boolean Since: clang-format 21

If true, overrides BinPackArguments when there are 20 or more items in a braced initializer list.

Example:

false:

vector<int> x{
    1,
    2,
    ...,
    20,
    21};

true:

vector<int> x{1, 2, ...,
              20, 21};

BinPackParameters

Pack function parameters together.

Type: BinPackParametersStyle Values:

• BinPack - Bin-pack parameters
• OnePerLine - All on current line if they fit, otherwise one per line
• AlwaysOnePerLine - Always put each parameter on its own line

Examples:

BinPack:

void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb,
       int ccccccccccccccccccccccccccccccccccccccccccc);

OnePerLine:

void f(int a, int b, int c);

void f(int a,
       int b,
       int ccccccccccccccccccccccccccccccccccccc);

AlwaysOnePerLine:

void f(int a,
       int b,
       int c);

Common Patterns

Conservative Breaking (Wide Lines)

ColumnLimit: 120
AllowShortFunctionsOnASingleLine: All
AllowShortIfStatementsOnASingleLine: AllIfsAndElse
AllowShortLoopsOnASingleLine: true
AllowShortBlocksOnASingleLine: Always
BreakBeforeBinaryOperators: None
BinPackArguments: true
BinPackParameters: BinPack

Aggressive Breaking (Narrow Lines)

ColumnLimit: 80
AllowShortFunctionsOnASingleLine: None
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
AllowShortBlocksOnASingleLine: Never
BreakBeforeBinaryOperators: All
BinPackArguments: false
BinPackParameters: Never
AlwaysBreakTemplateDeclarations: Yes

Balanced Breaking

ColumnLimit: 100
AllowShortFunctionsOnASingleLine: InlineOnly
AllowShortIfStatementsOnASingleLine: WithoutElse
AllowShortLoopsOnASingleLine: false
AllowShortBlocksOnASingleLine: Empty
BreakBeforeBinaryOperators: NonAssignment
BinPackArguments: true
BinPackParameters: BinPackFirstParameter

See Also

• Brace Styles - Configure brace placement
• Indentation - Control indentation
• Alignment - Align code elements
• Full Style Options Reference

---

← Prev: Alignment | Back to Index | Next: Braces →