Style formatting config needed (e.g. clang-format)
Functionality to add/problem to solve
Add a clang-format or similar system config file in the code repository, so that contributions to the repository or derived projects can follow the Coding Style Guide.
Clang-format is an established formatting tool and integration is already provided in many editors and IDEs, including Emacs, Vim, and CLion.
Target audience
- Regular developers of OpenFOAM
- External contributors to OpenFOAM
- Contributors to third-party OpenFOAM projects (e.g. function objects, such as the preCICE OpenFOAM adapter)
Proposal
- Create a
.clang-format
file, e.g. in the root directory of the repository, or any other directory preferred for developers' tools.- For example, with
clang-format -style=llvm -dump-config > .clang-format
- For example, with
- Define the preferred rules following the Clang-Format Style Options. Beware that the rules may depend on the Clang-Format version.
What does success look like, and how can we measure that?
Running clang-format -i FILES
should reformat the source files FILES
to follow the coding style guidelines.
Links / references
Funding
I am not aware of existing functionality regarding this. However, it may have been already developed by other developers.
No child items are currently assigned. Use child items to break down this issue into smaller parts.
Link issues together to show that they're related. Learn more.
Activity
This would indeed be great to have. Are the options for clang-format flexible enough to get the format we need?
- Owner
My feeling is no - have looked into this a few times over the last couple of years but results have not been satisfactory (as yet).
Happy to receive contributions!
- Maintainer
Hi @MakisH - do you actually have a functioning clang-format? I've also looking into this before and didn't get very far before finding that nothing fitted.
- Author
@mark I don't have anything for OpenFOAM, but we are now using (and probably soon enforcing) a config for preCICE (see scripts, config, and documentation).
Do you maybe have any halfway draft that we could look at together? I would be interested in looking into this to learn, but I am not sure I can do everything by myself from scratch.
Do you remember which rules were difficult to specify?
Also, since this is just formatting and you can automatically convert from one to another, how flexible would you be to adapt some (if any) "difficult" rules in order to get automatic formatting?
- Maintainer
Hi @MakisH
I don't have anything kicking around. I gave up fairly quickly when it seem that it wasn't going to go very far. Probably best if you try some configuration helper to see what can actually be tweaked. Must maintain
Allman
indentation, with the parameter line-breaks and outdented operators.I guess the rest will be a matter of seeing how far you get with clang-format. FWIW, I manage a very large majority of indenting with my editor settings. Should be fairly reasonable to read, and might be a good place to start. The style is "foam" jed editor cmode.sl
I have the same experience, took a quick look and concluded that customization is not quite as flexible as it would be needed. How much one would be prepared to sacrifice of the existing OF practice to confer to more establish formatting standards is a good question.
- Maintainer
If we got a bit close, might consider next checking on a clang/llvm forum about adding further customization options into clang. Might take a while, but would help for the long term. I guess this means that your first step is documenting the "gap" in requirements vs current capability.
- Author
Then I will have a look into it. It might take some time (as usual), but I will keep the issue up to date.
- Author
An update on this issue: I have now explored all (I hope) the options that clang-format can offer at the moment. I ended up with something close enough and I would welcome further feedback.
Since I do not have permission to submit Merge Requests here, I document the changes directly in the OpenFOAM-preCICE adapter repository: https://github.com/precice/openfoam-adapter/pull/173
- Maintainer
Getting closer, but still a number of misfeatures. I'll add comments on your precice github issue. Doesn't look like we are quite there yet.
Edited by Mark OLESEN I did some experients:
Whatstyle outputs this
BasedOnStyle: WebKit BraceWrapping: AfterClass: true AfterControlStatement: true AfterFunction: true AfterNamespace: true SplitEmptyFunction: false BreakBeforeBinaryOperators: None BreakBeforeBraces: Custom BreakBeforeInheritanceComma: true BreakConstructorInitializers: AfterColon MaxEmptyLinesToKeep: 2 SortIncludes: false SpaceBeforeCtorInitializerColon: false
Applying this to the src folder using
find . -name *.H -o -name *.C | xargs clang-format -i
still yields a quite large diff:
5984 files changed, 374841 insertions(+), 274285 deletions(-)
Which is quite large, considering that there are 6442 files and 680000 lines of code. If we introduce a formatter anyway, we can change the style however we want, so we should just choose the style we like the most, not the style that matches the current style the most. Any .clang-format file is better than not having a .clang-format file, because currently, we have to manually format everything, which is very time consuming.
For example:
Language: Cpp IndentWidth: 4 UseTab: Never BreakBeforeBraces: Allman InsertTrailingCommas: None NamespaceIndentation: None SortIncludes: false PointerAlignment: Left ColumnLimit: 0 MaxEmptyLinesToKeep: 2 BasedOnStyle: LLVM
- Maintainer
We probably wouldn't deviate that much from the current style. I generally get pretty good mileage with reasonably standard settings: https://github.com/olesenm/jed/blob/master/lib/cmode.sl#L1731 without very much manual fixup.
The ideal solution would be to extend the clang-formatter to handle more specifics, or at least enough to get closer. I tried seeing how/where the clang-formatter development is driven, but gave up fairly quickly.
We probably wouldn't deviate that much from the current style. I generally get pretty good mileage with reasonably standard settings: https://github.com/olesenm/jed/blob/master/lib/cmode.sl#L1731 without very much manual fixup.
I don't care which style gets choosing, I don't care what color the bikeshed gets. But we need some auto-formatter that can (also) be invoked as a command line tool ASAP because manual formatting is wasted time.
The ideal solution would be to extend the clang-formatter to handle more specifics, or at least enough to get closer.
That's wasted effort.
I tried seeing how/where the clang-formatter development is driven, but gave up fairly quickly.
The folder
./clang/tools/clang-format
in the llvm-repository. Devolpment works using https://llvm.org/docs/Phabricator.html- Please register or sign in to reply
Hi @mark,
I feel this (automated file formating) is really important, since otherwise a lot of energy and resources are spent on a quite tedious task. However, I don't think we can rely on
clang-format
alone, since OF has some peculiar styling rules. What I would suggest is to do the formatting in a two stage process:- Do a first formatting sweep with clang-format and get a good baseline;
- Post-process to fix formatting rules that are not possible with clang-format
I started some experiments here https://github.com/exasim-project/foam-format (currently WIP). But in any case it is clear that are quite some inconsistencies in the code base atm esp.:
- Whitespaces in for loop
for (label face=0; face<nFaces; face++)
vsfor (label face = 0; face < nFaces; face++)
- Whitespaces around algebraic operators like +*-/
Which need to either ignored or refactored at some time.
Edited by Gregor Olenik- Owner
@greole - how did you get on with your experiments?
- Author
I started a minimal working example in the SIG RSE repository, where we can experiment with different options. Please contribute merge requests there. The goal is not to merge each merge request, but to see the code and diff generated by different options.
I had another look at clang-format, and there seem to be no new options that address any of the issues I faced in 2021. I wrote a first post in the LLVM forum, but it did not get any optimistic feedback.
My next idea would be to automate the workflow of @mark (in case that is not already done). What would be the steps to open, format, and save a file in your editor of choice?
In the SIG RSE, we will discuss this tomorrow, hoping to come up with new ideas.
- Author
The general consensus today was that we do need an automatic solution, at least in the form of a good-enough specification that would first be adopted by downstream projects. I will try to discuss specific issues in the LLVM forum, but a main point is still "if the formatting is automatic, then it does not matter so much what the style is, even though it would be great to maintain the current style".
Please contribute ideas and suggestions in the minimal working example hosted in the SIG RSE repository and write further notes here.
The goal would be to show some progress/solutions in our next meeting, on Thursday, April 11, 13:00-14:30. Details on the wiki page.
This issue is already over 3 years old and I wouldn't want to wait another one. It seems we will have to change the style a little bit, but it is definitively worth it not having to do all the manual work anymore. Changing the style at some point, will be one
clang-format
command.All I want is some already existing, working tool, that integrates with my IDE/editor, can be called from CLI and added to a CI. I almost don't care e.g., whether there are spaces in a for loop or not.
Looking forward to discuss this in the MWE-repo mentioned by @MakisH and adding this to our project until summer.
- Author
We are attempting again to discuss this in the SIG Research Software Engineering this Thursday, April 11, 13:00-14:30: https://wiki.openfoam.com/Research_Software_Engineering_Special_Interest_Group
@MS has been pushing some suggestions in the minimal working example over the past two months, and @greole will also discuss the needs and practices from their project.
The more of you that join this discussion, the more chances we have to find solutions and make some progress.
I won't be able to join at 13:00, but I will join later, perhaps at 14:00.
Edited by Volker Weißmann
- Author
@mark could you please describe the exact process of formatting you are using? I have no experience with c-mode, but if this is documented somewhere, I could try finding some automatic solution based on that.
- Maintainer
Hey @MakisH
The c-mode formatting in Jed will be somewhat similar to Emacs (mostly). The regular entry point is "indent_line" (from the cmds.c file), which hooks back into the current mode. In this case, for C/C++/slang mode, that would be the
c_indent_line()
function contained in the cmode.sl file.For the editor, this function is normally bound to the
TAB
key (emacs bindings). If you read through the c_indent_line mode, you'll see that it is fairly ad hoc.- find the parse point
- determine the code context (eg, in comment, string or within real code)
- determine what the appropriate indentation level should be.
For OpenFOAM editing, this definitely helps a lot, but is also not fully automatic (think of it like an indentation co-pilot). What it does do is handle about 90-95% of the indentation alignments for OpenFOAM. What it does not do is modify code (eg, it does not add/remove brackets etc).
I nonetheless still find it useful since it helps catch stupid things (like an unmatched
{
or(
and lets me code without having to count indentation spaces. It doesn't do a great job with indenting a ternary, unless you enclose the entire thing in brackets, in which case it does a nice outdenting of the operators. It doesn't do very well with comma-separated items of an enum, nor with handling<<
indentation if the previous line ended with()
- it does work OK for the first occurrence, but does not attempt to do more backtracking than a single line. Most of the limitations don't really bother me much since the coding/algorithm aspects are what usually really slow me down.I wouldn't necessarily advocate that people start working with Jed, but at the time it was a really good multi-platform alternative with modest resource requirements.
The link to the meeting is here: https://bbb.in.tum.de/ger-ufs-vtx-wlg
- Author
I think we made some progress in today's meeting, thank you all for attending and contributing! We will now make more iterations in the repository and meet again in a month to directly discuss the status/outcomes.
Next meeting: Friday, May 10, 13:00-14:30 (UTC+1, Germany), again on https://bbb.in.tum.de/ger-ufs-vtx-wlg
Edited by Gerasimos Chourdakis Are you sure it is 13:00 CET? The last meeting was 13:00 CEST, i.e. 13:00 in "normal German time".
- Author
Well... good point! UTC+1 to be ISO-conforming.
(yes, "normal German time" is what I meant, and I am very happy to not be programming anything related to dates and timezones) - Maintainer
Yes I know that "in Bayern gehen die Uhren anders" - but the rest of Germany is currently on UTC+2 (ie, central European summer time).