[GRASS-dev] Proposal for using ClangFormat, replacing GNU indent, for C/C++ code formatting

[Nicklas Larsson]

I understand there is agreement on using the .clang-format formatting rules suggested with [1], which I just merged.

I have formatted the whole source base with clang-format v.15.0.6, in 7 different PRs [2-8]. I will start merging them tomorrow if there are no objections.

I have also filed a PR [9] which adds a CI check for clang-format errors.

Installing clang-format is perhaps most easily done with:
python -m pip install 'clang-format==15.0.6'

Formatting may be done with something like (following works on Mac):
find -E . -regex '.*\.(cpp|hpp|c|h)' -exec clang-format -i {} \+

Contribution rules must be updated, I will start putting up a draft ASAP.
Valuable inspiration may be taken from e.g. GDAL [10] and libtiff [11].

Cheers,
   Nicklas











Add .clang-format:
[1] https://github.com/OSGeo/grass/pull/2272

Format files:
[2] https://github.com/OSGeo/grass/pull/2709
[3] https://github.com/OSGeo/grass/pull/2710
[4] https://github.com/OSGeo/grass/pull/2711
[5] https://github.com/OSGeo/grass/pull/2712
[6] https://github.com/OSGeo/grass/pull/2713
[7] https://github.com/OSGeo/grass/pull/2714
[8] https://github.com/OSGeo/grass/pull/2715

CI check:
[9] https://github.com/OSGeo/grass/pull/2716

[10] https://lists.osgeo.org/pipermail/gdal-dev/2022-December/056658.html
[11] https://gitlab.com/libtiff/libtiff/-/merge_requests/431/diffs?commit_id=01cc265a7c7f24de14cda6dc40c960eb8c3c68bb

> On 5 Dec 2022, at 14:06, Nicklas Larsson via grass-dev <grass-dev at lists.osgeo.org> wrote:
> 
> Dear All,
> 
> I have put up a PR [1] with the intent to add a “.clang-format” file and ultimately replace the use of “GNU indent” [2] with ClangFormat [3] for formatting GRASS’ source code. ClangFormat, using the Clang compiler parser, is able to format any valid code in both C and C++. (In contrast to numerous problems and limitations with GNU indent).
> I’ve had the impression that this suggestion in general is a welcome one and not particularly controversial.
> 
> I have initially made the '.clang-format' to mirror as close as possible the settings in 'utils/grass_indent.sh' [4].
> 
> However, I'd like to propose changes to the (ClangFormat’s) “BreakBeforeBraces” rules [5]. The "GRASS"-style is a modified version of the GNU style. I think it would be preferable to simplify these rules with the so-called “Stroustrup” style, which is as close as it gets to K&R (in this regard) and also gives a slightly more compact code vertically. It can be described in short: braces start on new line *only* after functions, and 'else' and 'catch' start on new line after previous closing brace.
> 
> For example:
> 
> int f(void)
> {
>    if (...) {
>        ...
>    }
>    else {
>        ...
>    }
> }
> 
> All other cases -- enums, structs etc. -- attaches the starting brace, e.g.:
> 
> struct s {
>    ...
> }
> 
> 
> Please, check out the formatted example files in the PR [6] to see what the proposed changes would look like with the "Stroustrup" BreakBeforeBraces-rules (note: the PR aims to only add the '.clang-format' file).
> 
> I have intentionally left the setting of "ReflowComments" to the default 'true', which cleverly reformats comments extending the 80 columns. This causes some (aesthetic) issues with trailing Doxygen comments in mainly the in the 'include/grass/ and 'lib/' directories, which probably necessitates some initial manual work. On the other hand, a batch format of all module code will likely go pretty smoothly.
> 
> 
> 
> TO THIS INTENT, to finally solve the long extended problem with -- or lack of -- uniformly formatted code and not kicking this stone further down the road, I suggest the following:
> 
> 
> 1. We adapt the formatting policy using ClangFormat.
> 
> 2. We implement "BreakBeforeBraces" rules according the "Stroustrup" style.
> 
> 3. If there are no objections raised within a two weeks period, say until December 18, either to points 1 and/or 2 or even to this proposed deadline, the PR [1] will be merged and work can start on source code formatting.
> 
> 4. Any changes decided upon ought to be added to https://trac.osgeo.org/grass/wiki/Submitting/C
> 
> 
> 
> Cheers,
> Nicklas
> 
> 
> 
> 
> 
> [1] https://github.com/OSGeo/grass/pull/2272
> [2] https://www.gnu.org/software/indent/
> [3] https://clang.llvm.org/docs/ClangFormat.html
> [4] https://github.com/OSGeo/grass/blob/main/utils/grass_indent.sh
> [5] https://clang.llvm.org/docs/ClangFormatStyleOptions.html
> [6] https://github.com/OSGeo/grass/pull/2272/files
> 
> _______________________________________________
> grass-dev mailing list
> grass-dev at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/grass-dev