gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/01-alignment.md

Alignment Options

← Back to Index | CLI Usage | Next: Breaking →

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

Options for aligning code elements to improve readability and consistency.

Overview

Alignment options control how clang-format aligns various code elements vertically. These options help create visually organized code where related elements line up in columns.

Quick Examples

Aligned Assignments:

int a        = 1;
int somelongname = 2;
double c     = 3;

Aligned Declarations:

int         aaaa = 12;
float       b = 23;
std::string ccc = 23;

Aligned Macros:

#define SHORT_NAME       42
#define LONGER_NAME      0x007f
#define EVEN_LONGER_NAME (2)

Core Alignment Options

AlignAfterOpenBracket

Controls alignment of parameters after an opening bracket.

Type: BracketAlignmentStyle Values:

• Align - Align parameters on the open bracket
• DontAlign - Don't align, use ContinuationIndentWidth
• AlwaysBreak - Always break after bracket
• BlockIndent - Always break and increase indent

Examples:

Align:

someLongFunction(argument1,
                 argument2);

DontAlign:

someLongFunction(argument1,
    argument2);

AlwaysBreak:

someLongFunction(
    argument1, argument2);

BlockIndent:

someLongFunction(
    argument1,
    argument2
);

AlignArrayOfStructures

Align array of structures horizontally.

Type: ArrayInitializerAlignmentStyle Values:

• None - Don't align array initializers
• Left - Align and left-justify initializers
• Right - Align and right-justify initializers

Examples:

None:

struct test demo[] = {
    {56, 23, "hello"},
    {-1, 93463, "world"},
    {7, 5, "!"}
};

Left:

struct test demo[] = {
    {56,    23, "hello"},
    {-1, 93463, "world"},
    {7,      5, "!"    }
};

Right:

struct test demo[] = {
    {   56,    23, "hello"},
    {   -1, 93463, "world"},
    {    7,     5, "!"    }
};

AlignConsecutiveAssignments

Align consecutive assignment statements.

Type: AlignConsecutiveStyle Sub-options:

• Enabled (bool) - Enable alignment
• AcrossEmptyLines (bool) - Align across empty lines
• AcrossComments (bool) - Align across comments
• AlignCompound (bool) - Align compound assignments
• PadOperators (bool) - Pad operators to right

Examples:

Enabled: true:

int a            = 1;
int somelongname = 2;
double c         = 3;

Enabled: true, AcrossEmptyLines: true:

int a            = 1;
int somelongname = 2;

double c         = 3;
int d            = 4;

Enabled: true, AlignCompound: true:

a   &= 2;
bbb  = 2;

Enabled: true, PadOperators: true:

a   >>= 2;
bbb   = 2;

Shorthand:

# Boolean shorthand
AlignConsecutiveAssignments: true

# Full control
AlignConsecutiveAssignments:
  Enabled: true
  AcrossEmptyLines: false
  AcrossComments: true
  AlignCompound: true
  PadOperators: true

AlignConsecutiveBitFields

Align consecutive bit field declarations.

Type: AlignConsecutiveStyle

Example:

int aaaa : 1;
int b    : 12;
int ccc  : 8;

AlignConsecutiveDeclarations

Align consecutive declarations.

Type: AlignConsecutiveStyle Sub-options:

• Enabled (bool) - Enable alignment
• AcrossEmptyLines (bool) - Align across empty lines
• AcrossComments (bool) - Align across comments
• AlignFunctionDeclarations (bool) - Align function declarations
• AlignFunctionPointers (bool) - Align function pointers

Examples:

Enabled: true:

int         aaaa = 12;
float       b = 23;
std::string ccc;

Enabled: true, AcrossEmptyLines: true:

int         aaaa = 12;
float       b = 23;

std::string ccc;
int         d = 45;

Enabled: true, AlignFunctionDeclarations: true:

unsigned int f1(void);
void         f2(void);
size_t       f3(void);

Enabled: true, AlignFunctionPointers: true:

unsigned i;
int     &r;
int     *p;
int      (*f)();

AlignConsecutiveMacros

Align consecutive macro definitions.

Type: AlignConsecutiveStyle

Examples:

Enabled: true:

#define SHORT_NAME       42
#define LONGER_NAME      0x007f
#define EVEN_LONGER_NAME (2)
#define foo(x)           (x * x)

Enabled: true, AcrossEmptyLines: true:

#define SHORT_NAME       42
#define LONGER_NAME      0x007f

#define EVEN_LONGER_NAME (2)
#define foo(x)           (x * x)

AlignConsecutiveShortCaseStatements

Align consecutive short case labels.

Type: ShortCaseStatementsAlignmentStyle Sub-options:

• Enabled (bool)
• AcrossEmptyLines (bool)
• AcrossComments (bool)
• AlignCaseColons (bool) - Align case colons
• AlignCaseArrows (bool) - Align case arrows (for languages like Verilog)

Example:

Enabled: true:

switch (x) {
case 1:  return "one";
case 2:  return "two";
case 10: return "ten";
}

Enabled: true, AlignCaseColons: true:

switch (x) {
case 1  : return "one";
case 2  : return "two";
case 10 : return "ten";
}

AlignEscapedNewlines

Align escaped newlines in macros.

Type: EscapedNewlineAlignmentStyle Values:

• DontAlign - Don't align
• Left - Align to the left
• Right - Align to the right
• LeftWithLastLine - Align to left, but relative to last line

Examples:

Left:

#define A \
  int aaaa; \
  int b; \
  int dddddddddd;

Right:

#define A                                                                      \
  int aaaa;                                                                    \
  int b;                                                                       \
  int dddddddddd;

AlignOperands

Align operands of binary and ternary expressions.

Type: OperandAlignmentStyle Values:

• DontAlign - Don't align
• Align - Align operands
• AlignAfterOperator - Align after operators

Examples:

Align:

int aaa = bbbbbbbbbbbbbbb +
          ccccccccccccccc;

AlignAfterOperator:

int aaa = bbbbbbbbbbbbbbb
        + ccccccccccccccc;

AlignTrailingComments

Align trailing comments.

Type: TrailingCommentsAlignmentStyle Sub-options:

• Kind - Alignment kind (Leave, Always, Never)
• OverEmptyLines - Lines to align over

Examples:

Kind: Always:

int a;      // Comment a
int b = 2;  // Comment b

Kind: Always, OverEmptyLines: 1:

int a;  // Comment a

int b;  // Comment b (aligned with comment a)

Shorthand:

# Boolean shorthand
AlignTrailingComments: true

# Full control
AlignTrailingComments:
  Kind: Always
  OverEmptyLines: 0

TableGen-Specific Alignment

These options apply specifically to LLVM TableGen code.

AlignConsecutiveTableGenBreakingDAGArgColons

Align colons in breaking DAG arguments.

Type: AlignConsecutiveStyle

AlignConsecutiveTableGenCondOperatorColons

Align colons in condition operators.

Type: AlignConsecutiveStyle

AlignConsecutiveTableGenDefinitionColons

Align colons in definitions.

Type: AlignConsecutiveStyle

Common Patterns

Minimal Alignment (Performance-Focused)

AlignAfterOpenBracket: DontAlign
AlignConsecutiveAssignments: false
AlignConsecutiveBitFields: false
AlignConsecutiveDeclarations: false
AlignConsecutiveMacros: false
AlignEscapedNewlines: DontAlign
AlignOperands: DontAlign
AlignTrailingComments: false

Maximum Alignment (Readability-Focused)

AlignAfterOpenBracket: Align
AlignArrayOfStructures: Left
AlignConsecutiveAssignments:
  Enabled: true
  AcrossEmptyLines: true
  AcrossComments: true
  AlignCompound: true
  PadOperators: true
AlignConsecutiveBitFields:
  Enabled: true
AlignConsecutiveDeclarations:
  Enabled: true
  AlignFunctionDeclarations: true
  AlignFunctionPointers: true
AlignConsecutiveMacros:
  Enabled: true
  AcrossEmptyLines: true
AlignEscapedNewlines: Right
AlignOperands: Align
AlignTrailingComments:
  Kind: Always
  OverEmptyLines: 1

Moderate Alignment (Balanced)

AlignAfterOpenBracket: Align
AlignConsecutiveAssignments: false
AlignConsecutiveBitFields: true
AlignConsecutiveDeclarations: false
AlignConsecutiveMacros: true
AlignEscapedNewlines: Right
AlignOperands: Align
AlignTrailingComments: true

Tips

1. Performance Impact: Extensive alignment can make diffs noisier and may slow formatting slightly
2. Maintenance: Aligned code may require more adjustments when making changes
3. Consistency: Choose alignment settings that match your team's preferences
4. Selective Use: Consider aligning only specific elements (e.g., macros but not assignments)
5. Empty Lines: Use AcrossEmptyLines carefully as it can create large alignment blocks

See Also

• Breaking & Line Wrapping - Control where lines break
• Indentation - Control indentation behavior
• Spacing - Fine-tune whitespace
• Full Style Options Reference

---

← Back to Index | CLI Usage | Next: Breaking →