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

[Nicklas Larsson]

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