[WIP] pre-commit: set up clang-format hook

[EZoni]

This PR introduces a prototype for adding the clang-format hook to pre-commit.

To disable formatting, e.g., on blocks of mathematical formulas, use:

// clang-format off
amrex::Real x = my     * custom
              + pretty * alignment;
// clang-format on

Currently, the hook is applied only to the Source/main.cpp file to demonstrate its functionality.

If this approach is deemed useful, we can gradually extend it to all C++ files in our codebase, one PR at a time. We could make this into a GitHub "project" to easily keep track of the progress. If not, please feel free to close the PR without merging.

The .clang-format configuration file has been generated based on the LLVM style using the command

clang-format -style=llvm -dump-config > .clang-format

and has been modified in the following ways:

• AlwaysBreakAfterDefinitionReturnType: All  # instead of None
  

• IndentWidth: 4  # instead of 2
  

• PointerAlignment: Left  # instead of Right
  

• SpaceBeforeParens: Custom  # instead of ControlStatements
  SpaceBeforeParensOptions:
    ...
    AfterFunctionDefinitionName: true  # instead of false
    AfterFunctionDeclarationName: true  # instead of false
    ...
  

A different base style could be chosen and/or further customization could be done in future PRs as needed, when the formatting is applied to more code.

[dpgrote]

Having a formatting standard is a good idea - thanks!
However, my own preference is to have a space before and after the ampersand, since to me it is easier to read.

auto & warpx = WarpX::GetInstance();

In .clang-format, this would be

ReferenceAlignment: Middle

[EZoni]

Thanks, @dpgrote! This is exactly the kind of feedback process I was hoping for regarding this formatting effort. I am personally fine with your preference, so I implemented the change. Others can chime in as well.

[EZoni]

We could also run the new clang-format hook on more complex files in this PR, e.g., WarpX.H and WarpX.cpp, and see what other rules we would like to customize before we move forward with the rest of the codebase in separate PRs.

[roelof-groenewald]

I agree having a standard formatting would be great. The rules set so far look good to me and, as you said, we can refine as we go.

[lucafedeli88]

Thanks for this PR, @EZoni ! I agree with @roelof-groenewald that having standard formatting is good.

About the rules that you have set, I have to confess that I am not a big fan of ReferenceAlignment: Middle , because when I see something likeA & B I immediately think or "A logical_and B" rather than "B is a reference to type A".
My personal preference on this point is left alignment, because when I see A& I immediately think "type is reference to A". However, I agree that it is a bit less visible and I am OK with the other options for "ReferenceAlignment" if other maintainers prefer them.

Concerning the other rules that you have set, I like them!

[EZoni]

About the rules that you have set, I have to confess that I am not a big fan of ReferenceAlignment: Middle , because when I see something likeA & B I immediately think or "A logical_and B" rather than "B is a reference to type A".
My personal preference on this point is left alignment, because when I see A& I immediately think "type is reference to A". However, I agree that it is a bit less visible and I am OK with the other options for "ReferenceAlignment" if other maintainers prefer them.

Thanks, @lucafedeli88! If there are conflicting opinions on ReferenceAlignment perhaps we can have an internal vote in the technical committee.

Note that the default LLVM style recommends A &B = C, which matches the alignment they recommend for pointers A *B = C. In fact, they set ReferenceAlignment = Pointer and PointerAlignment = Right, by default.

[WeiqunZhang]

WarpX(development)$ git grep "[[:alnum:]]\s&[[:alnum:]]" Source/ | wc -l
271

WarpX(development)$ git grep "[[:alnum:]]\s&\s[[:alnum:]]" Source/ | wc -l
828

WarpX(development)$ git grep "[[:alnum:]]&\s[[:alnum:]]" Source/ | wc -l
3966

[EZoni]

Also interesting for more context, from Bjarne Stroustrup's C++ Style and Technique FAQ: https://www.stroustrup.com/bs_faq2.html#whitespace.

[ax3l]

Not sure if I shared this before, but we have clang-format integration in openPMD-api as a GH workflow & pre-commit hook:

• https://github.com/openPMD/openPMD-api/tree/dev/.github/workflows
• https://github.com/openPMD/openPMD-api/blob/0.16.1/.pre-commit-config.yaml#L65-L79