gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/03-braces.md

Brace Styles

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

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

Configure brace placement and wrapping for various code constructs.

Overview

Brace style is one of the most visible formatting choices. clang-format supports all major brace styles through the BreakBeforeBraces option and fine-grained control via BraceWrapping.

BreakBeforeBraces

The main option controlling brace style.

Type: BraceBreakingStyle

Predefined Styles

Attach (K&R style)

namespace N {
class C {
  void f() {
    if (x) {
    } else {
    }
  }
};
}

Linux

namespace N
{
class C
{
  void f()
  {
    if (x) {
    } else {
    }
  }
};
}

Mozilla

namespace N {
class C
{
  void f()
  {
    if (x) {
    } else {
    }
  }
};
}

Stroustrup

namespace N {
class C {
  void f()
  {
    if (x) {
    }
    else {
    }
  }
};
}

Allman

namespace N
{
class C
{
  void f()
  {
    if (x)
    {
    }
    else
    {
    }
  }
};
}

Whitesmiths

namespace N
  {
class C
  {
  void f()
    {
    if (x)
      {
      }
    else
      {
      }
    }
  };
  }

GNU

namespace N
{
class C
  {
    void f()
      {
        if (x)
          {
          }
        else
          {
          }
      }
  };
}

WebKit

namespace N {
class C {
  void f()
  {
    if (x) {
    } else {
    }
  }
};
}

Custom

Use Custom to configure individual brace wrapping with BraceWrapping.

BreakBeforeBraces: Custom
BraceWrapping:
  AfterFunction: true
  AfterControlStatement: Never
  # ... more options

BraceWrapping

Fine-grained control over brace wrapping when BreakBeforeBraces: Custom.

Type: BraceWrappingFlags

Sub-Options

AfterCaseLabel

Wrap case labels.

Type: Boolean

Example:

true:

switch (foo)
{
  case 1:
  {
    bar();
    break;
  }
  default:
  {
    plop();
  }
}

false:

switch (foo) {
  case 1: {
    bar();
    break;
  }
  default: {
    plop();
  }
}

AfterClass

Wrap class definitions.

Type: Boolean

Example:

true:

class foo
{};

false:

class foo {};

AfterControlStatement

Wrap control statements (if/for/while/switch).

Type: BraceWrappingAfterControlStatementStyle Values:

• Never - Never wrap
• MultiLine - Wrap if multi-line
• Always - Always wrap

Examples:

Never:

if (foo) {
} else {
}
for (int i = 0; i < 10; ++i) {
}

MultiLine:

if (foo) {
} else {
}
for (int i = 0; i < 10; ++i)
{
}

Always:

if (foo)
{
}
else
{
}
for (int i = 0; i < 10; ++i)
{
}

AfterEnum

Wrap enum definitions.

Type: Boolean

Example:

true:

enum X : int
{
  B
};

false:

enum X : int { B };

AfterFunction

Wrap function definitions.

Type: Boolean

Example:

true:

void foo()
{
  bar();
}

false:

void foo() {
  bar();
}

AfterNamespace

Wrap namespace definitions.

Type: Boolean

Example:

true:

namespace
{
int foo();
}

false:

namespace {
int foo();
}

AfterStruct

Wrap struct definitions.

Type: Boolean

Example:

true:

struct foo
{
  int x;
};

false:

struct foo {
  int x;
};

AfterUnion

Wrap union definitions.

Type: Boolean

Similar to AfterStruct.

AfterExternBlock

Wrap extern blocks.

Type: Boolean

Example:

true:

extern "C"
{
  int foo();
}

false:

extern "C" {
  int foo();
}

AfterObjCDeclaration

Wrap ObjC definitions (interfaces, implementations...).

Type: Boolean

Note: @autoreleasepool and @synchronized blocks are wrapped according to AfterControlStatement flag.

BeforeCatch

Wrap before catch.

Type: Boolean

Example:

true:

try {
  foo();
}
catch () {
}

false:

try {
  foo();
} catch () {
}

BeforeElse

Wrap before else.

Type: Boolean

Example:

true:

if (foo()) {
}
else {
}

false:

if (foo()) {
} else {
}

BeforeLambdaBody

Wrap before lambda body.

Type: Boolean

Example:

true:

connect(
  []()
  {
    foo();
    bar();
  });

false:

connect(
  []() {
    foo();
    bar();
  });

BeforeWhile

Wrap before while in do-while.

Type: Boolean

Example:

true:

do {
  foo();
}
while (1);

false:

do {
  foo();
} while (1);

IndentBraces

Indent wrapped braces themselves.

Type: Boolean

Example:

true:

void foo()
  {
  if (true)
    {
    }
  }

false:

void foo()
{
  if (true)
  {
  }
}

SplitEmptyFunction

Split empty functions.

Type: Boolean

Example:

true:

int f()
{
}

false:

int f() {}

SplitEmptyRecord

Split empty classes/structs.

Type: Boolean

Example:

true:

class Foo
{
}

false:

class Foo {}

SplitEmptyNamespace

Split empty namespaces.

Type: Boolean

Similar to SplitEmptyRecord.

Related Options

BracedInitializerIndentWidth

Indent width for braced initializers.

Type: Integer Default: If unset or negative, ContinuationIndentWidth is used

Example:

BracedInitializerIndentWidth: 2:

void f() {
  SomeClass c{
    "foo",
    "bar",
    "baz",
  };
  auto s = SomeStruct{
    .foo = "foo",
    .bar = "bar",
    .baz = "baz",
  };
  SomeArrayT a[3] = {
    {
      foo,
      bar,
    },
    {
      foo,
      bar,
    },
    SomeArrayT{},
  };
}

InsertBraces

Automatically insert optional braces after control statements.

Type: Boolean Default: false

Example:

true:

if (isa<FunctionDecl>(D)) {
  handleFunctionDecl(D);
} else if (isa<VarDecl>(D)) {
  handleVarDecl(D);
} else {
  return;
}

while (i--) {
  for (auto *A : D.attrs()) {
    handleAttr(A);
  }
}

do {
  --i;
} while (i);

false:

if (isa<FunctionDecl>(D))
  handleFunctionDecl(D);
else if (isa<VarDecl>(D))
  handleVarDecl(D);
else
  return;

while (i--)
  for (auto *A : D.attrs())
    handleAttr(A);

do
  --i;
while (i);

Warning: Insert braces after control statements (if, else, for, do, and while) in C++ unless the control statements are inside macro definitions or the braces would enclose preprocessor directives. Setting this option to true could lead to incorrect code formatting due to clang-format's lack of complete semantic information. As such, extra care should be taken to review code changes made by this option.

RemoveBracesLLVM

Remove optional braces of control statements according to the LLVM coding style.

Type: Boolean Default: false

Example:

true:

if (isa<FunctionDecl>(D))
  handleFunctionDecl(D);
else if (isa<VarDecl>(D))
  handleVarDecl(D);

if (isa<VarDecl>(D)) {
  for (auto *A : D.attrs())
    if (shouldProcessAttr(A))
      handleAttr(A);
}

if (isa<FunctionDecl>(D))
  for (auto *A : D.attrs())
    handleAttr(A);

if (auto *D = (T)(D)) {
  if (shouldProcess(D))
    handleVarDecl(D);
  else
    markAsIgnored(D);
}

if (a)
  b();
else if (c)
  d();
else
  e();

false:

if (isa<FunctionDecl>(D)) {
  handleFunctionDecl(D);
} else if (isa<VarDecl>(D)) {
  handleVarDecl(D);
}

if (isa<VarDecl>(D)) {
  for (auto *A : D.attrs()) {
    if (shouldProcessAttr(A)) {
      handleAttr(A);
    }
  }
}

if (isa<FunctionDecl>(D)) {
  for (auto *A : D.attrs()) {
    handleAttr(A);
  }
}

if (auto *D = (T)(D)) {
  if (shouldProcess(D)) {
    handleVarDecl(D);
  } else {
    markAsIgnored(D);
  }
}

if (a) {
  b();
} else {
  if (c) {
    d();
  } else {
    e();
  }
}

Warning: Remove optional braces of control statements (if, else, for, and while) in C++ according to the LLVM coding style. This option will be renamed and expanded to support other styles. Setting this option to true could lead to incorrect code formatting due to clang-format's lack of complete semantic information. As such, extra care should be taken to review code changes made by this option.

Common Brace Styles

K&R / Kernel Style (Attach)

BreakBeforeBraces: Attach

int foo() {
    if (true) {
        return 0;
    } else {
        return 1;
    }
}

Allman / BSD Style

BreakBeforeBraces: Allman

int foo()
{
    if (true)
    {
        return 0;
    }
    else
    {
        return 1;
    }
}

Stroustrup Style

BreakBeforeBraces: Stroustrup

int foo()
{
    if (true) {
        return 0;
    }
    else {
        return 1;
    }
}

Linux Kernel Style

BreakBeforeBraces: Linux

namespace N
{
int foo()
{
    if (true) {
        return 0;
    } else {
        return 1;
    }
}
}

Custom: Functions Only

BreakBeforeBraces: Custom
BraceWrapping:
  AfterFunction: true
  AfterClass: false
  AfterStruct: false
  AfterControlStatement: Never
  BeforeElse: false
  BeforeCatch: false

class Foo {
    void bar()
    {
        if (x) {
        } else {
        }
    }
};

Custom: Maximum Wrapping

BreakBeforeBraces: Custom
BraceWrapping:
  AfterCaseLabel: true
  AfterClass: true
  AfterControlStatement: Always
  AfterEnum: true
  AfterFunction: true
  AfterNamespace: true
  AfterObjCDeclaration: true
  AfterStruct: true
  AfterUnion: true
  AfterExternBlock: true
  BeforeCatch: true
  BeforeElse: true
  BeforeLambdaBody: true
  BeforeWhile: true
  IndentBraces: false
  SplitEmptyFunction: true
  SplitEmptyRecord: true
  SplitEmptyNamespace: true

Tips

1. Consistency: Choose one style and stick with it across your project
2. Team Preference: Match your team's existing conventions
3. Language Idioms: Some languages have stronger conventions (e.g., Java typically uses Attach style)
4. Readability: Consider what's most readable for your codebase's complexity
5. Diff Size: Styles with more wrapping create larger diffs when changing code

See Also

• Breaking & Line Wrapping - Control line breaks
• Indentation - Control indentation within braces
• Quick Reference - Complete configuration examples
• Full Style Options Reference

---

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