gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/08-comments.md

Comments & Miscellaneous Options

← Prev: Languages | Back to Index | Next: Advanced →

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

Comment formatting and miscellaneous options.

Comment Formatting

ReflowComments

Comment reformatting style.

Type: ReflowCommentsStyle Default: Always Version: clang-format 3.8

Values:

• Never - Leave comments untouched
• Always - Apply indentation rules and reflow long comments into new lines, trying to obey the ColumnLimit

Example:

Always:

// This is a very long comment that will be automatically
// reflowed to fit within the column limit when enabled

Never:

// This is a very long comment that will not be reflowed even if it exceeds column limit

CommentPragmas

A regular expression that describes comments with special meaning, which should not be split into lines or otherwise changed.

Type: String Default: ^\\s*IWYU pragma: Version: clang-format 3.7

Comments matching this regex will not be reflowed.

Example:

CommentPragmas: "^ FOOBAR pragma:"

#include <vector> // FOOBAR pragma: keep

FixNamespaceComments

Add/fix end-of-namespace comments for namespaces and fixes invalid existing ones. This doesn't affect short namespaces, which are controlled by ShortNamespaceLines.

Type: Boolean Default: true Version: clang-format 5

Example:

true:

namespace longNamespace {
void foo();
void bar();
} // namespace longNamespace

namespace shortNamespace {
void baz();
}

false:

namespace longNamespace {
void foo();
void bar();
}

namespace shortNamespace {
void baz();
}

CompactNamespaces

If true, consecutive namespace declarations will be on the same line. If false, each namespace is declared on a new line.

Type: Boolean Default: false Version: clang-format 5

Example:

true:

namespace Foo { namespace Bar {
}}

false:

namespace Foo {
namespace Bar {
}
}

ShortNamespaceLines

The maximal number of unwrapped lines that a short namespace spans. Defaults to 1.

Type: Unsigned Default: 1 Version: clang-format 13

This determines the maximum length of short namespaces by counting unwrapped lines (i.e. containing neither opening nor closing namespace brace) and makes FixNamespaceComments omit adding end comments for those.

Example:

ShortNamespaceLines: 1:

namespace a {
  int foo;
}

namespace b {
  int foo;
  int bar;
} // namespace b

ShortNamespaceLines: 0:

namespace a {
  int foo;
} // namespace a

namespace b {
  int foo;
  int bar;
} // namespace b

WrapNamespaceBodyWithEmptyLines

Wrap namespace body with empty lines.

Type: WrapNamespaceBodyWithEmptyLinesStyle Version: clang-format 20

Values:

• Never - Remove all empty lines at the beginning and the end of namespace body
• Always - Always have at least one empty line at the beginning and the end of namespace body except that the number of empty lines between consecutive nested namespace definitions is not increased
• Leave - Keep existing newlines at the beginning and the end of namespace body. MaxEmptyLinesToKeep still applies

Example:

Never:

namespace N1 {
namespace N2 {
function();
}
}

Always:

namespace N1 {
namespace N2 {

function();

}
}

Leave:

// Keeps existing empty lines as they are

Macros

AttributeMacros

A vector of strings that should be interpreted as attributes/qualifiers instead of identifiers. This can be useful for language extensions or static analyzer annotations.

Type: List of Strings Version: clang-format 12

Example:

AttributeMacros: [__capability, __output, __unused]

x = (char *__capability)&y;
int function(void) __unused;
void only_writes_to_buffer(char *__output buffer);

ForEachMacros

A vector of macros that should be interpreted as foreach loops instead of as function calls.

Type: List of Strings Version: clang-format 3.7

These are expected to be macros of the form:

FOREACH(<variable-declaration>, ...)
  <loop-body>

Example:

ForEachMacros: [RANGES_FOR, FOREACH]

For example: BOOST_FOREACH

FOREACH(item, list) {
  doSomething(item);
}

IfMacros

A vector of macros that should be interpreted as conditionals instead of as function calls.

Type: List of Strings Version: clang-format 13

These are expected to be macros of the form:

IF(...)
  <conditional-body>
else IF(...)
  <conditional-body>

Example:

IfMacros: [IF]

For example: KJ_IF_MAYBE

StatementAttributeLikeMacros

Macros which are ignored in front of a statement, as if they were an attribute. So that they are not parsed as identifier, for example for Qt's emit.

Type: List of Strings Version: clang-format 12

Example:

AlignConsecutiveDeclarations: true
StatementAttributeLikeMacros: []
unsigned char data = 'x';
emit          signal(data); // This is parsed as variable declaration.

AlignConsecutiveDeclarations: true
StatementAttributeLikeMacros: [emit]
unsigned char data = 'x';
emit signal(data); // Now it's fine again.

StatementMacros

A vector of macros that should be interpreted as complete statements.

Type: List of Strings Version: clang-format 8

Typical macros are expressions and require a semicolon to be added. Sometimes this is not the case, and this allows to make clang-format aware of such cases.

Example:

For example: Q_UNUSED

StatementMacros:
  - Q_UNUSED
  - QT_REQUIRE_VERSION

TypenameMacros

A vector of macros that should be interpreted as type declarations instead of as function calls.

Type: List of Strings Version: clang-format 9

These are expected to be macros of the form:

STACK_OF(...)

Example:

For example: OpenSSL STACK_OF, BSD LIST_ENTRY

TypenameMacros:
  - STACK_OF
  - LIST

WhitespaceSensitiveMacros

A vector of macros which are whitespace-sensitive and should not be touched.

Type: List of Strings Version: clang-format 11

These are expected to be macros of the form:

STRINGIZE(...)

Example:

For example: BOOST_PP_STRINGIZE

WhitespaceSensitiveMacros:
  - STRINGIZE
  - PP_STRINGIZE

Line Endings and Formatting Control

LineEnding

Line ending style (\n or \r\n) to use.

Type: LineEndingStyle Version: clang-format 16

Values:

• LF - Use \n (Unix/Linux/Mac)
• CRLF - Use \r\n (Windows)
• DeriveLF - Use \n unless the input has more lines ending in \r\n
• DeriveCRLF - Use \r\n unless the input has more lines ending in \n

Example:

LineEnding: LF        # Unix/Linux/Mac
LineEnding: CRLF      # Windows
LineEnding: DeriveLF  # Auto-detect, prefer LF

DeriveLineEnding

DEPRECATED - This option is deprecated. See DeriveLF and DeriveCRLF of LineEnding.

Automatically detect line ending style.

Type: Boolean Default: true Version: clang-format 10

UseCRLF

DEPRECATED - This option is deprecated. See LF and CRLF of LineEnding.

Use Windows-style line endings (CRLF).

Type: Boolean Default: false Version: clang-format 10

Example:

true - Use \r\n (Windows) false - Use \n (Unix/Linux/Mac)

DisableFormat

Completely disable formatting.

Type: Boolean

When true, clang-format won't modify the file at all.

InsertNewlineAtEOF

Insert newline at end of file.

Type: Boolean

Ensures file ends with a newline character.

KeepFormFeed

Keep form feed characters.

Type: Boolean

Preserves ASCII form feed characters (\f) in source.

Trailing Commas

InsertTrailingCommas

Automatically insert trailing commas.

Type: TrailingCommaStyle Values:

• None - Don't insert trailing commas
• Wrapped - Insert trailing commas in wrapped function calls

Example:

Wrapped (JavaScript):

const x = {
  a: 1,
  b: 2, // trailing comma added
};

EnumTrailingComma

Insert a comma (if missing) or remove the comma at the end of an enum enumerator list.

Type: EnumTrailingCommaStyle Version: clang-format 21

Warning: Setting this option to any value other than Leave 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.

Values:

• Leave - Don't insert or remove trailing commas
• Insert - Insert trailing commas

Example:

Leave:

enum { a, b, c, };
enum Color { red, green, blue };

Insert:

enum { a, b, c, };
enum Color { red, green, blue, };

Integer Literals

IntegerLiteralSeparator

Configure digit separators in integer literals.

Type: IntegerLiteralSeparatorStyle Sub-options:

• Binary - Separator for binary literals (0b)
• BinaryMinDigits - Minimum digits for binary
• Decimal - Separator for decimal
• DecimalMinDigits - Minimum digits for decimal
• Hex - Separator for hexadecimal
• HexMinDigits - Minimum digits for hex

Example:

IntegerLiteralSeparator:
  Binary: 4
  Decimal: 3
  Hex: 2

int a = 100'000'000;   // Decimal separator every 3 digits
int b = 0b1010'1010;   // Binary separator every 4 digits
int c = 0xDEAD'BEEF;   // Hex separator every 2 digits

Empty Lines

EmptyLineAfterAccessModifier

Add empty line after access modifiers.

Type: EmptyLineAfterAccessModifierStyle Values:

• Never, Leave, Always

Example:

Always:

class Foo {
private:

  int x;
public:

  void bar();
};

EmptyLineBeforeAccessModifier

Add empty line before access modifiers.

Type: EmptyLineBeforeAccessModifierStyle Values:

• Never, Leave, Always, LogicalBlock

Example:

Always:

class Foo {
  int x;

private:
  int y;

public:
  void bar();
};

Pointer and Reference Alignment

PointerAlignment

Alignment of pointers and references.

Type: PointerAlignmentStyle Values:

• Left - Align to left
• Right - Align to right
• Middle - Align to middle

Examples:

Left:

int* a;
int& b;

Right:

int *a;
int &b;

Middle:

int * a;
int & b;

DerivePointerAlignment

Derive pointer alignment from existing code.

Type: Boolean

When true, overrides PointerAlignment based on majority style in file.

ReferenceAlignment

Separate alignment for references (overrides PointerAlignment for references).

Type: ReferenceAlignmentStyle Values:

• Pointer - Same as pointers
• Left, Right, Middle

Qualifier Alignment

QualifierAlignment

Position of const/volatile qualifiers.

Type: QualifierAlignmentStyle Values:

• Leave - Don't change
• Left - const int
• Right - int const
• Custom - Use QualifierOrder

Example:

Left:

const int a;
const int* b;

Right:

int const a;
int const* b;

QualifierOrder

Custom qualifier order when QualifierAlignment: Custom.

Type: List of Strings

Example:

QualifierAlignment: Custom
QualifierOrder:
  - inline
  - static
  - constexpr
  - const
  - volatile
  - type

Common Patterns

Namespace and Comment Handling

FixNamespaceComments: true
CompactNamespaces: false
ReflowComments: true
CommentPragmas: "^ IWYU pragma:|^ NOLINT"

Line Endings

Modern (v16+):

LineEnding: DeriveLF # Auto-detect, prefer Unix
InsertNewlineAtEOF: true

Legacy (deprecated):

DeriveLineEnding: true # DEPRECATED - use LineEnding: DeriveLF
UseCRLF: false # DEPRECATED - use LineEnding: LF
InsertNewlineAtEOF: true

Pointer Style (Left-Aligned)

PointerAlignment: Left
ReferenceAlignment: Left
DerivePointerAlignment: false

Pointer Style (Right-Aligned)

PointerAlignment: Right
ReferenceAlignment: Right
DerivePointerAlignment: false

Tips

1. Comment Reflow: Disable ReflowComments if you have carefully formatted comments
2. Namespace Comments: FixNamespaceComments helps navigate large codebases
3. Namespace Empty Lines: Use WrapNamespaceBodyWithEmptyLines (v20+) to control empty lines in namespace bodies
4. Macro Lists: Maintain accurate macro lists for correct formatting
5. Pointer Alignment: Choose one style and enforce it with DerivePointerAlignment: false
6. Line Endings: Use LineEnding: DeriveLF (v16+) for mixed-platform teams. Replaces deprecated DeriveLineEnding and UseCRLF
7. Trailing Commas: Useful in JavaScript/TypeScript for cleaner diffs
8. Enum Trailing Commas: Use EnumTrailingComma (v21+) carefully, as it may cause formatting issues
9. Integer Separators: Improves readability of large numeric literals

See Also

• Spacing - Control whitespace
• Languages - Language-specific options
• Advanced - Experimental features
• Full Style Options Reference

---

← Prev: Languages | Back to Index | Next: Advanced →