29129, "jabraham17", "auto-format compiler and runtime", "2026-07-14T18:02:56Z"
This issue is to file the future desire to automatically format the compiler and runtime and enforce that behavior via the CI
The motivation for this is maintainability and consistency. Developers usually have strong opinions about code formatting. With many developers working on a project, there can be many conflicting opinions. Its important for developers to use the same style to avoid churn in the same code that has nothing to do with the actual logic of the code. This keeps the code more maintainable, as over time if someone does not enforce the style the code will diverge and different parts of the codebase (or even across the same function!) will look different. This creates unnecessary mental load for developers working on the code and reviewing the code.
By introducing an auto-formatter, the burden of who ensures the code is consistent is put on a tool rather than relying on fallible humans. Many large, distributed open source projects have auto-formatters to ensure consistency across a large and diverse developer pool.
I strongly believe we should auto-format the runtime and compiler. In Apply clang-format to the Chapel compiler by jabraham17 · Pull Request #29113 · chapel-lang/chapel · GitHub, I created a formatting style that resembles the currently implemented style for the compiler as closely as possible (using the frontend style as a tiebreaker when the production compiler differs)
The format I came up with is
# Chapel compiler C++ formatting style.
BasedOnStyle: LLVM
Language: Cpp
# Includes are grouped and ordered by hand, so don't let clang-format sort them.
SortIncludes: false
IndentWidth: 2
ContinuationIndentWidth: 2
# 'public:' / 'private:' / 'protected:' sit one space in from the class body.
AccessModifierOffset: -1
# Namespace bodies are not indented (contents start at column 0).
NamespaceIndentation: None
FixNamespaceComments: false
IndentCaseLabels: true
# Constructor initializer lists break before the colon, indented two spaces.
BreakConstructorInitializers: BeforeColon
ConstructorInitializerIndentWidth: 2
PointerAlignment: Left
DerivePointerAlignment: false
MaxEmptyLinesToKeep: 1
# Don't reflow or rewrap comment text; doc comments (/** ... */), including
# embedded \rst blocks, are hand-formatted and must be left intact.
ReflowComments: Never
AlignConsecutiveAssignments: None
AlignConsecutiveDeclarations: None
AlignConsecutiveMacros: Consecutive
AlignEscapedNewlines: LeftWithLastLine
AlignTrailingComments:
Kind: Always
OverEmptyLines: 0
AlignConsecutiveShortCaseStatements:
Enabled: false
AllowShortCaseLabelsOnASingleLine: true
AllowShortFunctionsOnASingleLine: All
AllowShortIfStatementsOnASingleLine: WithoutElse
AllowShortLambdasOnASingleLine: All
AllowShortLoopsOnASingleLine: true
# When a call or signature wraps, arguments align under the open paren and
# each goes on its own line rather than being bin-packed.
AlignAfterOpenBracket: Align
BinPackParameters: false
BinPackArguments: false
It seems there is currently no strong consensus among the current core developers to actually do this right now (but much stronger desire to do it in the future), so I am filing this to log the desire
The following script can be used to apply the format and commit the changes
#!/usr/bin/env bash
#
# Apply clang-format to each subdirectory of compiler/ and frontend/,
# committing the result of each subdirectory separately.
#
set -euo pipefail
# Resolve repo root based on this script's location (util/devel/).
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
cd "$REPO_ROOT"
FORMAT_SCRIPT="./util/devel/apply-clang-format.sh"
if [[ ! -x "$FORMAT_SCRIPT" ]]; then
echo "error: cannot find executable $FORMAT_SCRIPT" >&2
exit 1
fi
for parent in compiler frontend; do
for dir in "$parent"/*/; do
dir="${dir%/}" # strip trailing slash
echo "==> Formatting $dir"
"$FORMAT_SCRIPT" "$dir"
# Stage any changes within this subdirectory.
git add -- "$dir"
# Only commit if this subdirectory produced staged changes.
if git diff --cached --quiet -- "$dir"; then
echo " no changes in $dir, skipping commit"
else
git commit -sm "clang-format $dir" -- "$dir"
echo " committed changes in $dir"
fi
done
done
echo "Done."