11 KiB
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 wrapMultiLine- Wrap if multi-lineAlways- 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
- Consistency: Choose one style and stick with it across your project
- Team Preference: Match your team's existing conventions
- Language Idioms: Some languages have stronger conventions (e.g., Java typically uses Attach style)
- Readability: Consider what's most readable for your codebase's complexity
- 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