[clang-format] Add an option to support the placement of commas before the parameters in the line break format. #152032
Description
Feature Request: Support for Leading Comma Style in Function Calls and Lists
Summary
This is a feature request to add support for leading commas in multi-line formatting of function arguments, parameter lists, and similar constructs in clang-format.
Currently, ClangFormat only supports the trailing comma style:
do_something(arg1,
arg2,
arg3
);The proposed feature is to optionally format this as:
do_something( arg1
, longarg2
, longarg3
);Although trailing commas are the convention in most C++ style guides, leading commas offer practical advantages in code maintenance and readability:
✅ Clear vertical alignment: All parameters begin with the same structure (, + expression), improving readability especially with longer expressions.
✅ Minimal diff impact: The probability of making a modification on the first line is lower compared to the last line, when a comma is placed before the last line, the modification on the last line becomes more favorable.
✅ Structural clarity: Commas serve as visible "leaders" for lines in a list, making the structure of the list more obvious at a glance.
✅ Improved error avoidance: Avoids errors from forgetting to add a trailing comma when copy-pasting, especially with string lists or initializer lists.
std::vector<std::string> items = {
"xxxxxxxxxxxxxxxxxxxxxx",
"xxxxxxxxxxxxxxxxxxx",
"xxxxxxxxxxxxxxx" // <-- Missing comma here is visually subtle
"xxxxxxxxxxxxxxxxxxxxxx",
"xxxxxxxxxxxxxxx"
};This compiles, but silently concatenates the second and third strings, creating a subtle and dangerous bug that may go unnoticed.
Leading comma style:
std::vector<std::string> items = {
"xxxxxxxxxxxxxxxxxxxxxx"
,"xxxxxxxxxxxxxxxxxxx"
"xxxxxxxxxxxxxxx" // <-- Missing comma here breaks the visual pattern
,"xxxxxxxxxxxxxxxxxxxxxx"
,"xxxxxxxxxxxxxxx"
};✅ Consistency with expression semantics: The comma operator in C++ is left-associative and binds expressions; the leading-comma format better reflects this grouping when broken across lines.
These benefits are particularly noticeable in:
Function call arguments
Constructor initializer lists
Enum or array initializations
Logging or tracing macro argument lists
Use Case Example
Given a function call with multiple arguments:
log_event("device_id"
,"timestamp"
,"event_type"
,"severity"
);This format reduces mental overhead when quickly scanning logs or comparing calls side by side. It's also more robust during frequent additions or deletions of parameters.
Proposed Configuration
A new configuration key in .clang-format:
CommaStyle: Leading | Trailing # Default: Trailing
When set to Leading, clang-format would place commas at the beginning of each new line when breaking function arguments, initializer lists, etc.
Compatibility
This change should be opt-in only, preserving default trailing-comma behavior. It could be implemented with minimal impact to current formatting logic, restricted to line break formatting contexts.
Related Context
Leading commas are common in some functional languages (e.g., Elm, Haskell) and are used in some large internal C++ codebases that prioritize diff minimalism and structural clarity. Other tools and formatters like Prettier (JavaScript) have had similar feature discussions.
Conclusion
Adding a CommaStyle: Leading option would improve the flexibility of clang-format, making it suitable for a broader range of style preferences and maintenance workflows. It supports users who value clarity, alignment, and diff minimalism, without impacting those who prefer the default trailing style.