Add clang-format file

[netmindz]

Rather than just describing what code style we look for, it would be good to provide a clang-format file

To get us started I have created one based on a style detection tool and one of the current files

In order to verify if the file is right, we can run clang-format -i wled00/*.cpp and if we have the right values then all the changes should match our expectations

We might not choose to mass reformat all existing code, but it serves as useful test to check that new code being written will indeed conform to our style

I very much welcome input from others, especially those with knowledge of how to write a clang-format file

Summary by CodeRabbit

• Chores
  • Added a project-wide code-formatting configuration based on Google style guidelines.
  • Enabled consistent formatting while preserving comments, selected compact code constructs, and modern constructor syntax.
  • Updated repository settings so the formatting configuration is tracked and applied.
  • Added safeguards to exclude third-party and generated source code from automatic formatting.
  • Documented compatibility with clang-format 16 and newer.

[w00000dy]

I think that's a very good idea.
The question is, do we want a .clang-format file that is as close as possible to the current WLED code, or do we want a .clang-format file that also fixes some of the unattractive things in the WLED code?

[netmindz]

That's where I've stumbled a bit to be honest @w00000dy
If you use on of the automated tools to help build a clang file against current code then you get slightly different rules depending on which file you use as your reference

[w00000dy]

Since you wanted some feedback, I had a look at it. I've written what I think about a few options. The following options are suggestions for additions to the .clang-format file from my side:

• InsertNewlineAtEOF: true
• AllowShortBlocksOnASingleLine: true

AllowShortBlocksOnASingleLine allows this:

while (true) {}

and

while (true) { continue; }

[w00000dy]

This formats this:

float fmod_t(float num, float denom) {
  int tquot = num / denom;
  float res = num - tquot * denom;
  return res;
}

to this:

float fmod_t(float num, float denom) {
  int   tquot = num / denom;
  float res = num - tquot * denom;
  return res;
}

I prefer the first version.

[softhack007]

I agree - the extra spaces in int tquot - to visually align it with the definition of float fmod_t - are confusing.

[w00000dy]

Why do you want to set this to None?

Now this formats this:

int add(int a, int b) { return a + b; }

to this:

int add(int a, int b) {
  return a + b;
}

[w00000dy]

In the rare case that this happens, I think aligning would improve readability here.

[w00000dy]

I think this was set because of your tool. I see no reason why we should set this to DontAlign since aligning would improve readability.

[w00000dy]

I think in the rare case where we exceed the ColumnLimit, aligning would improve readability.

[w00000dy]

The BreakConstructorInitializersBeforeComma should be replaced with the BreakConstructorInitializers option.

https://reviews.llvm.org/D32479

[w00000dy]

This option is deprecated. See: https://clang.llvm.org/docs/ClangFormatStyleOptions.html#keepemptylinesatthestartofblocks

[w00000dy]

Maybe we should change this so that the code doesn't take up so many lines?

[w00000dy]

Maybe we should at least set this to IndentOnly so that misaligned comments are formatted.

[w00000dy]

Why not?

[netmindz]

Thank you @w00000dy for your comments, this is my first time using clang and I'm not a C++ developer I am very grateful for input from those with experience.

I'll have a look through your individual comments when I get time to do so

[github-actions]

Hey! This pull request has been open for quite some time without any new comments now. It will be closed automatically in a week if no further activity occurs.
Thank you for contributing to WLED! ❤️

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d56cd96d-5a67-4f7c-bfe5-00d36a2049b2

📥 Commits

Reviewing files that changed from the base of the PR and between db6236e and 6d1cc5d.

📒 Files selected for processing (2)

• .clang-format
• wled00/src/.clang-format

🚧 Files skipped from review as they are similar to previous changes (1)

• .clang-format

---

Walkthrough

Added tracked clang-format configuration at the repository root and under wled00/src. Removed the root configuration from .gitignore. No functional code or public API declarations changed.

Changes

Clang-format configuration

Layer / File(s)	Summary
Root formatting rules .clang-format	Added documented Google-based formatting rules, compatibility settings, line-width and comment handling options, blank-line preservation, and include-order preservation.
Source formatting exclusion wled00/src/.clang-format	Disabled formatting for vendored and generated code under wled00/src.
Repository ignore update .gitignore	Removed .clang-format from the ignored paths so the root configuration can be tracked.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding clang-format configuration files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (3)

.clang-format (3)

3-3: Reconsider disabling bracket alignment
AlignAfterOpenBracket: DontAlign prevents aligning parameters, which can hurt readability in multi-line calls. Consider enabling alignment for consistency.

---

7-7: Revisit trailing comments alignment
AlignTrailingComments: false will leave trailing comments unaligned. Consider IndentOnly to maintain comment indentation consistency.

---

14-14: ⚠️ Potential issue

Deprecated option used for constructor initializers
BreakConstructorInitializersBeforeComma is deprecated. Replace with the modern BreakConstructorInitializers setting:

-BreakConstructorInitializersBeforeComma: true
+BreakConstructorInitializers: BeforeComma

🧹 Nitpick comments (2)

.clang-format (2)

8-8: AllowAllArgumentsOnNextLine consideration
AllowAllArgumentsOnNextLine: false forbids moving all function arguments to the next line, which may reduce readability for long signatures. Consider enabling it.

---

13-13: Ternary operator breaks
BreakBeforeTernaryOperators: false compacts ternary expressions but can hinder readability for complex conditions. Consider setting it to true.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 18e0ec9 and 16c91b6.

📒 Files selected for processing (2)

• .clang-format (1 hunks)
• .gitignore (0 hunks)

💤 Files with no reviewable changes (1)

• .gitignore

🔇 Additional comments (14)

.clang-format (14)

1-2: Baseline Style Confirmation
BasedOnStyle: Google and the YAML header are correctly set to anchor on the Google style.

---

4-4: Approve consecutive declarations alignment
AlignConsecutiveDeclarations: Consecutive will line up declarations nicely, improving readability.

---

5-5: Escaped newlines alignment
AlignEscapedNewlines: DontAlign is sensible to avoid unpredictable indent shifts with escaped line breaks.

---

6-6: Operand alignment disabled
AlignOperands: DontAlign matches Google style and avoids uneven spacing in expressions.

---

9-11: Short constructs formatting
AllowShortCaseLabelsOnASingleLine: true, AllowShortFunctionsOnASingleLine: None, and AllowShortIfStatementsOnASingleLine: Always align with Google style and look appropriate.

---

12-12: Multiline strings behavior
AlwaysBreakBeforeMultilineStrings: false preserves the original formatting of long strings. This is reasonable if you want to keep manual line breaks.

---

15-15: String literal breaks
BreakStringLiterals: false prevents splitting string literals. This is fine if preserving literal integrity is a priority.

---

16-16: Column limit sanity check
ColumnLimit: 240 is much wider than typical guidelines (80–100). Confirm this is intentional for display configurations.

---

17-17: Continuation indent width
ContinuationIndentWidth: 2 follows Google style and ensures consistent indentation for wrapped lines.

---

18-18: Preprocessor directive indent
IndentPPDirectives: BeforeHash is less common than AfterHash. Verify that macro and conditional directive formatting meets expectations.

---

20-20: Empty lines retention
MaxEmptyLinesToKeep: 2 prevents excessive blank lines and is a good default.

---

21-21: Comment reflow disabled
ReflowComments: false preserves manual comment formatting. Good if you want to control wording and layout.

---

22-22: Include sorting policy
SortIncludes: Never disables automatic include sorting. Confirm this aligns with the project's manual include grouping conventions.

---

23-23: Trailing comment spacing
SpacesBeforeTrailingComments: 1 is standard practice and looks correct.

[coderabbitai]

⚠️ Potential issue

Deprecated empty-lines option
KeepEmptyLinesAtTheStartOfBlocks is deprecated. Update to the current equivalent (e.g., KeepEmptyLinesAtTopOfFunctions).

🤖 Prompt for AI Agents

In the .clang-format file at line 19, replace the deprecated option
KeepEmptyLinesAtTheStartOfBlocks with the current equivalent option
KeepEmptyLinesAtTopOfFunctions to ensure compatibility with the latest
clang-format versions.

[w00000dy]

Please don't close this PR. I would like the idea of this PR

[softhack007]

@CodeRabbit please re-review.

Additionally, summarize the style changes suggested in the review comments, together with a short description of what each change achieves.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch all review comments on PR `#4238`
gh pr view 4238 --repo wled/WLED --json reviews,reviewRequests,comments 2>/dev/null | jq '.comments[] | {author: .author.login, body: .body}' 2>/dev/null || true

# Also fetch the review comments (inline diff comments)
gh api repos/wled/WLED/pulls/4238/comments --paginate 2>/dev/null | jq '.[] | {user: .user.login, body: .body, path: .path, line: .line}' 2>/dev/null || true

# And PR reviews
gh api repos/wled/WLED/pulls/4238/reviews --paginate 2>/dev/null | jq '.[] | {user: .user.login, body: .body, state: .state}' 2>/dev/null || true

# Read the .clang-format file from the PR branch
cat .clang-format 2>/dev/null || true

Length of output: 19551

---

@softhack007, here is a full summary of the style changes suggested across the review comments from @w00000dy and the previous CodeRabbit pass, along with what each change achieves.

---

Summary of Suggested Changes to .clang-format

🔴 Deprecations / Bugs (must fix)

Option	Current Value	Suggested Change	Why
BreakConstructorInitializersBeforeComma	true	Replace with BreakConstructorInitializers: BeforeComma	The current option is deprecated (removed upstream); using it risks silent mis-formatting on newer clang-format versions.
KeepEmptyLinesAtTheStartOfBlocks	true	Replace with KeepEmptyLinesAtTopOfFunctions: true (or false)	This option is deprecated in newer clang-format releases and will be ignored without warning.

---

🟠 Alignment Settings (currently too restrictive)

Option	Current Value	Suggested Change	What it achieves
AlignAfterOpenBracket	DontAlign	Align (or remove to use Google default)	Aligns wrapped function arguments/parameters under the opening bracket, improving readability of long signatures.
AlignConsecutiveDeclarations	Consecutive	Remove / set to None	The current setting pads type names with spaces to vertically align identifiers in consecutive declarations (e.g., adds spaces after int to align with float). @w00000dy considers the unpadded version more readable.
AlignEscapedNewlines	DontAlign	Left or Right	Aligns the backslash \ at the end of multi-line macro definitions to a consistent column, making macros easier to read.
AlignOperands	DontAlign	Align	Aligns binary/ternary operands vertically in multi-line expressions, which improves readability when lines are broken.
AlignTrailingComments	false	IndentOnly	Ensures trailing comments (// …) are at least correctly indented even if not fully column-aligned, preventing visually misaligned comments.

---

🟡 Short-construct Behavior

Option	Current Value	Suggested Change	What it achieves
AllowShortFunctionsOnASingleLine	None	Inline or All	None forces even trivial one-liner functions (e.g. int add(int a, int b) { return a + b; }) to be split across multiple lines. Enabling it keeps compact functions on one line, matching common WLED style.
AllowAllArgumentsOnNextLine	false	true	Allows all arguments of an over-long call to be moved to the next line as a group, rather than breaking them individually — often cleaner for long function calls.
BreakBeforeTernaryOperators	false	true	Breaks before ? and : in ternary expressions rather than after, which many find more readable for complex conditions.

---

🟢 Proposed Additions

Option	Suggested Value	What it achieves
InsertNewlineAtEOF	true	Ensures every file ends with a newline, which is required by POSIX and avoids noisy diffs.
AllowShortBlocksOnASingleLine	true (or Empty)	Allows empty or trivially-short blocks (e.g. while (true) {}) to remain on a single line, matching current WLED style.

---

⚪ Open Questions

Option	Current Value	Question raised
MaxEmptyLinesToKeep	2	@w00000dy suggests potentially lowering this to 1 to keep code less sprawling.
ReflowComments	false	@w00000dy suggests IndentOnly as a middle ground: doesn't reflow comment text but still fixes indentation of misaligned comment lines.
SortIncludes	Never	@w00000dy questions whether this should remain disabled — enabling it (true or IncludeBlocks: Regroup) would enforce consistent #include ordering but could disrupt manually ordered includes in WLED (e.g. platform-specific guards). This is a project-level policy decision.
ColumnLimit	240	Notably wide (typical is 80–120). Confirmed as intentional for WLED given wide monitor usage, but worth documenting explicitly.

---

Triggering a fresh re-review now.

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-04-10T11:41:46.737Z
Learning: In the WLED repository (wled/WLED), trailing-whitespace removals or other pure-whitespace "optimizations" must NOT be intermixed with real code/logic changes in the same PR. Reviewers prefer whitespace cleanup to be submitted in a dedicated, separate PR. Reason: intermixing makes diffs harder to read (obscures actual logic changes) and causes trouble when cherry-picking commits. Always flag PRs that mix whitespace-only edits with functional changes and ask the contributor to separate them.

---

Learnt from: CR
Repo: wled/WLED PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-12T07:15:56.657Z
Learning: Match existing code style in files you edit; C++ formatting is available via `clang-format` but is not in CI

---

Learnt from: CR
Repo: wled/WLED PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-12T07:15:56.657Z
Learning: Document changes in pull requests with clear description of what changed and why, including expected impact on user-visible behavior, related issue links, and screenshots for new features

✅ Actions performed

Full review triggered.

[coderabbitai]

♻️ Duplicate comments (1)

.clang-format (1)

14-19: ⚠️ Potential issue | 🟠 Major

Replace deprecated clang-format keys (tooling compatibility risk).

Line 14 and Line 19 use deprecated options. Please migrate to current keys so this file stays valid across newer clang-format versions.

🔧 Proposed fix

-BreakConstructorInitializersBeforeComma: true
+BreakConstructorInitializers: BeforeComma
@@
-KeepEmptyLinesAtTheStartOfBlocks: true
+KeepEmptyLinesAtTopOfFunctions: true

In current clang-format documentation, is `BreakConstructorInitializersBeforeComma` deprecated in favor of `BreakConstructorInitializers`? Also, is `KeepEmptyLinesAtTheStartOfBlocks` deprecated in favor of `KeepEmptyLinesAtTopOfFunctions`?

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.clang-format around lines 14 - 19, Replace the two deprecated clang-format
options: change BreakConstructorInitializersBeforeComma to the modern
BreakConstructorInitializers and preserve the choice (e.g., BeforeComma) as its
value, and change KeepEmptyLinesAtTheStartOfBlocks to
KeepEmptyLinesAtTopOfFunctions keeping the boolean value; update these keys in
the file where the existing deprecated options appear so the config uses
BreakConstructorInitializers and KeepEmptyLinesAtTopOfFunctions instead of the
old names.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In @.clang-format:
- Around line 14-19: Replace the two deprecated clang-format options: change
BreakConstructorInitializersBeforeComma to the modern
BreakConstructorInitializers and preserve the choice (e.g., BeforeComma) as its
value, and change KeepEmptyLinesAtTheStartOfBlocks to
KeepEmptyLinesAtTopOfFunctions keeping the boolean value; update these keys in
the file where the existing deprecated options appear so the config uses
BreakConstructorInitializers and KeepEmptyLinesAtTopOfFunctions instead of the
old names.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 90629ca7-779f-4696-84a4-e20ea90fca7d

📥 Commits

Reviewing files that changed from the base of the PR and between ba377d7 and db6236e.

📒 Files selected for processing (2)

• .clang-format
• .gitignore

💤 Files with no reviewable changes (1)

• .gitignore

[netmindz]

Pushed an update that trims this down to a minimal, empirically-tuned rule set — 24 keys → 12 — based on measuring the formatted diff against the real wled00 source rather than debating options in the abstract. Summary for reviewers:

Method

For every contested option (from @w00000dy's review and CodeRabbit's passes), I checked out upstream main's wled00/*.cpp/*.h (68 files) and measured how many lines clang-format would change for each candidate value. A lot of the original file's overrides turned out to be actively worse than just leaving Google's default alone — e.g. IndentPPDirectives: BeforeHash cost ~650 extra changed lines vs. Google's default None; SpacesBeforeTrailingComments: 1 cost ~250 vs. the default 2. Those are simply dropped now rather than replaced — the fix was mostly subtraction, not addition.

Since this PR isn't proposing a mass reformat (existing style stays as-is; new/touched code converges going forward), I also spot-checked the finalists with clang-format -lines= range formatting (the actual usage mode) rather than trusting whole-file diff counts alone.

The standout keep: AlignTrailingComments: Leave

This one isn't about aggregate line count — it's about what happens when a contributor edits one line inside an existing comment-aligned block:

// before, only the "second" line gets touched:
int a = 1;      // first
int bb = 2;     // second - EDIT THIS LINE
int ccc = 3;    // third

// AlignTrailingComments: Never (or false) collapses just the touched line's spacing:
int a = 1;      // first
int bb = 2;  // second - EDIT THIS LINE      <- now misaligned with its neighbours
int ccc = 3;    // third

// AlignTrailingComments: Leave preserves it untouched:
int a = 1;      // first
int bb = 2;     // second - EDIT THIS LINE   <- unchanged
int ccc = 3;    // third

Leave requires clang-format 16+ (its Kind-based syntax). Given that trade-off, this needs clang-format 16+ as the floor for the whole file — flagging this explicitly as a compatibility decision for maintainers to weigh in on, since anyone on an older clang-format gets a hard parse error (no formatting at all) rather than a silent difference.

Correcting a CodeRabbit suggestion

CodeRabbit's fix for the KeepEmptyLinesAtTheStartOfBlocks deprecation warning was KeepEmptyLinesAtTopOfFunctions. I tested it directly against clang-format 14, 16, 18, and 22 — it's an unknown key that hard-errors on all four. The modern nested replacement (KeepEmptyLines: {AtStartOfBlock: true}) also errors on 16 and 18 (only became valid later). The old deprecated scalar spelling parses cleanly across the entire 14–22 range, so it's kept intentionally rather than "fixed" — noting this so it doesn't get re-flagged.

BreakConstructorInitializersBeforeComma → BreakConstructorInitializers: BeforeComma is a safe rename (verified on all four versions), so that one's updated.

AllowShortIfStatementsOnASingleLine: AllIfsAndElse

Un-deprecates the old Always value (no longer a valid enum member) and picks the modern spelling closest to what it aliased to. Verified with range-formatting that it can't reach into an untouched sibling if/else branch — clang-format's line-range restriction is a hard boundary, so this only affects the branch actually being edited.

One caveat worth knowing: IndentPPDirectives: None

Existing code is mostly flush-left on nested #if directives, so None (Google's default) matches more often than BeforeHash did. But it's not free: touching a line inside one of the rarer indented nested blocks (e.g. the FXparticleSystem.h guard in FX.cpp) will flush just that touched directive left against its still-indented siblings. The reverse problem exists with BeforeHash against the (much more common) flush-left blocks, so this is a net improvement, not a strict win — just flagging it so it's not a surprise later.

New file: wled00/src/.clang-format

wled00/src/ holds vendored third-party code (dependencies/: json, fastled_slim, espalexa, e131, dmx, ws2812fx, etc.) and generated font headers (font/), none of which follows WLED's style. Child .clang-format files fully replace the parent's config for their subtree (no merging), so a DisableFormat: true there stops the root config from reaching in and reformatting upstream/generated code.

Net result

14,036 lines would change if the whole wled00 were reformatted with the final config, vs. 17,996 with the file as it stood before this update, and 22,860 for plain BasedOnStyle: Google — but since this PR doesn't reformat anything, the more relevant framing is that the config now sits measurably closer to existing convention with fewer, better-justified overrides.