Move from astyle to clang-format for C++ code formatting
elpaso opened this issue · comments
QGIS Enhancement: Move from astyle to clang-format for C++ code formatting
Date 2023/04/05
Author Alessandro Pasotti (@elpaso)
Contact elpaso at itopen dot it
maintainer @elpaso
Version QGIS 3.34
Summary
QGIS is currently using astyle (Artistic Style) to format code, while this has been working well so far, we have sometimes hit the limits of the tool (see NOPAD in src code) and it's probably a good time to move to a more powerful and modern tool.
Proposed Solution
clang-format is the ideal candidate, it is much more usable in practice because it understands more of the syntax of C++ (rather than just relying on heuristics/pattern-matching) so it's much less prone to getting edge cases wrong.
Affected Files
All C++ source code files.
Performance Implications
None
Further Considerations/Improvements
GDAL and GEOS have been recently gone through this process, see: https://gdal.org/development/rfc/rfc69_cplusplus_formatting.html and https://trac.osgeo.org/geos/wiki/RFC4
clang-format is also available as a pre-commit hook (see: https://github.com/pre-commit/mirrors-clang-format), I will file a sepatate QEP for the adoption of the pre-commit https://pre-commit.com/ framework for the cross-platform management of all our pre-commit hooks, currently implemented as separate scripts.
The downside of this move is that we will have to make a "big reformat" commit in order to reformat all the code, but this will have to be done only once, unless we opt for an incremental approach (reformat each file whenever it is touched/changed).
Backwards Compatibility
None
Votes
(required)
A big +1 from me.
We've made some tries in the past and I believe we can get close to no-modification of our source files.
The main issue we had was the indent of access modifiers (see https://bugs.llvm.org/show_bug.cgi?id=19056 and https://reviews.llvm.org/D60225) which was finally solved in 2021 (see https://reviews.llvm.org/rG2a42c759ae7bb09dd448d188138f310d014fcab6).
This would mean LLVM 12+ and this is probably acceptable now!
Another point regarding modification of headers is … sipify… As you probably don't want to dig into this, that's a good motivation to stick to our current format :) (just the format, not the tool!)
And that would mean one tool to rule all the branches, otherwise, we'll probably live with astyle with the current branches until they are not maintained anymore and clang-format for the new ones, but that's not a big deal.
+1 to use a simple pre-commit for this kind of task :-)
Precommit looks good, from a few projets using it.
And that would mean one tool to rule all the branches, otherwise, we'll probably live with astyle with the current branches until they are not maintained anymore and clang-format for the new ones, but that's not a big deal.
The backport bot will mainly fail if the formatting is different between active branches so it will require a lof manual backport.
Precommit looks good, from a few projets using it.
And that would mean one tool to rule all the branches, otherwise, we'll probably live with astyle with the current branches until they are not maintained anymore and clang-format for the new ones, but that's not a big deal.
The backport bot will mainly fail if the formatting is different between active branches so it will require a lof manual backport.
Right, I guess we will need to reformat all the "active" branches.
For reference, for QField clang-format is used with the following options which offer a (IMHO) acceptable compatibility. It's been a while, so maybe nowadays even better things are possible: https://github.com/opengisch/QField/blob/master/.clang-format with https://github.com/opengisch/QField/blob/master/.pre-commit-config.yaml#L43-L47
A big +1 from me too. I use it on various projects and it's excellent (especially since it's been stabilized since versions ~ >= 12).
fyi, I've discovered a tool - Clang Format Detector that "promises" to convert file styles to .clang-format. I don't have a truly satisfactory result yet, but it's pretty close.