microsoft / microsoft/STL

Report clang-format issues

Open
#2,475 10 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

compiler
Dominant language
C++
Stars
11.1k
Forks
1.7k
Avg merge
4d 15h
Merged PRs (30d)
22

Description

We have a lot of workarounds for clang-format misbehavior. If anyone has free time, it would be very helpful to identify the top issues causing problems, prepare reduced test cases, and report them upstream. (Or fix them, if anyone wants to become a clang-format contributor.) Some issues may already be known: https://github.com/llvm/llvm-project/issues?q=is%3Aissue+is%3Aopen+label%3Aclang-format

We often use // clang-format off so that can be a good way to find examples - try removing it and see if something egregious happens. (However, not every occurrence of // clang-format off is working around misbehavior. Sometimes clang-format would do a reasonable job, but we have a particular cosmetic preference, or need to match the formatting of external code. xcharconv_ryu.h is an example of "match external code".) Another common workaround is an empty comment // at the end of a line to force line wrapping.

A non-exhaustive list of common problems:

  • clang-format sometimes handles concepts poorly, particularly requires expressions (and we have particular preferences for requires stuff versus requires(stuff) versus requires (stuff) depending on the code).
    • Especially see #2064: clang-format 12 has extreme trouble with complex non-parenthesized requires-clauses, even within // clang-format off - it gets confused about the level of indentation and damages the rest of the file. We need to add parentheses in order to avoid this.
  • Variable templates are commonly mishandled, and we love variable templates so this affects us everywhere.
  • In certain situations, clang-format doesn't respect our 120-column limit.
  • The documentation at https://releases.llvm.org/13.0.0/tools/clang/docs/ClangFormatStyleOptions.html contains numerous typos, some of which significantly affect usability. (e.g. SpacesInLineCommentPrefix is extremely damaged)

We love clang-format 😻 which is why we've formatted the entire STL since VS 2019 16.0 and have a validator that breaks the build when a file isn't clang-formatted. We just want it to be even better!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Search the repository for // clang-format off, empty trailing comments, and examples such as xcharconv_ryu.h; review #2064 and the listed ClangFormatStyleOptions documentation. Reduce individual formatting failures to reproducible cases, then report them upstream or fix them. Done means the problematic cases are clearly documented or resolved without breaking the formatter validator.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation, tooling
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.