contributing: Add .clang-format

[nilason]

This is a suggestion to replace GNU indent with clang-format.

Attempting to bulk process the code base with util/grass_indent_ALL.sh as reported in #1630 (and noticed in #2270) a number of problem occurs. This is caused by limited functionality and lack of active development on GNU indent.
However, bulk processing with clang-format causes no error, thanks to the fact that it is backed by a full C and (!) C++ code parser.
Replacing the GRASS formatting tool to clang-format may be the better bet for the future.

Initially I put this up as a draft, for testing and discussion. I tried to get the settings as close as the present style guide, the one notable deviation (I could discover so far) is with alignment of trailing comments.

The .clang-format file is created with clang-format version 13.

Note: only the addition of the .clang-format is the ultimate goal for this PR. The added commit with all the formatted source files are for illustration only.

To test this locally:

find -E . -regex '.*\.(cpp|hpp|c|h)' -exec clang-format -style=file -i {} \;

for testing alternative settings see https://clang.llvm.org/docs/ClangFormatStyleOptions.html

For reference, description of the settings in util/grass_indent.sh:

-npro	Do not read `.indent.pro' files.
-bad	Force blank lines after the declarations.
-bap	Force blank lines after procedure bodies.
-bbb	Force blank lines before block comments.
-br	Put braces on line with if, etc.
-bli0	Indent braces n spaces.
-bls	Put braces on the line after struct declaration lines.
-cli0	Case label indent of n spaces.
-ncs	Do not put a space after cast operators.
-fc1	Format comments in the first column.
-hnl	Prefer to break long lines at the position of newlines in the input.
-i4	Set indentation level to n spaces.
-nbbo	Do not prefer to break long lines before boolean operators.
-nbc	Do not force newlines after commas in declarations.
-nbfda	Don't put each argument in a function declaration on a separate line.
-nbfde	--dont-break-function-decl-args-end
-ncdb	Do not put comment delimiters on blank lines.
-ncdw	Do not cuddle } and the while of a do {} while;.
-nce	Do not cuddle } and else.
-nfca	Do not format any comments.
-npcs	Do not put space after the function in function calls.
-nprs	Do not put a space after every '(' and before every ')'.
-npsl	Put the type of a procedure on the same line as its name.
-nsc	Do not put the `*' character at the left of comments.
-nsob	Do not swallow optional blank lines.
-saf	Put a space after each for.
-sai	Put a space after each if.
-saw	Put a space after each while.
-sbi0	Indent braces of a struct, union or enum N spaces.
-ss	On one-line for and while statements, force a blank before the semicolon.
--no-tabs	Use spaces instead of tabs.

[wenzeslaus]

+1 given the advantages of clang-format over GNU Indent (also considering we may want to indent modern C++). My experience is that clang-format is not stable in between versions, so to check with exact version in the CI, we need to use DoozyX/clang-format-lint-action. We will also need to update it time to time like we did with Black before it was stable (and still will have to update but with less changes in the source code).

BTW, the actual formatting (formatting only) changes should go to .git-blame-ignore-revs (#1391) - add add to git-blame-ignore-revs to the PR and after merge, create another PR to update the file.

[nilason]

Just updated the .clang-format file. The closest ClangFormat style to ours is the one of LLVM, the file now reflects that and only the deviating settings are not commented out.

I also limited the number of formatted example files, for better and quicker overview online.

+1 given the advantages of clang-format over GNU Indent (also considering we may want to indent modern C++). My experience is that clang-format is not stable in between versions, so to check with exact version in the CI, we need to use DoozyX/clang-format-lint-action. We will also need to update it time to time like we did with Black before it was stable (and still will have to update but with less changes in the source code).

Yes, I'm aware of this circumstances with ClangFormat versions, but I think the advantages compared to GNU indent are worth it. You're right, Black is a good parallel.

[nilason]

For reference, https://lists.osgeo.org/pipermail/grass-dev/2022-March/095621.html.

[nilason]

Fixed some more settings to get even closer to present "GRASS" style and updated the demo files accordingly.

GRASS style's BreakBeforeBraces is now custom, but to use one of the builtin brace breaking styles the following cases (and only those) need to be changed to the following:

Mozilla:

class UntypedStream
{

...

 } else {

Stroustrup:

enum rule_type {

...

struct Cell_head {

...

typedef union _dglHeapData {

...

extern "C" {

Linux:

enum AMI_stream_type {

...

struct Cell_head {

...

union {

...

class AMI_STREAM : public UntypedStream
{

...

 } else {

...

 extern "C" {
 

WebKit:

enum AMI_stream_type {

...

struct Cell_head {

...

union {

...

 } else {

...

extern "C" {

Even though I'm perfectly ok with present GRASS style, I must say I personally prefer to convert to Stroustrup brace breaking style.

[neteler]

@nilason would you mind to redo the reformatting afresh on top of the current state of "main"?

[nilason]

@nilason would you mind to redo the reformatting afresh on top of the current state of "main"?

Certainly! Hopefully this crazy busy summer will soon reach the end. I look forward to return to a more active contribution. :-)

[nilason]

@nilason would you mind to redo the reformatting afresh on top of the current state of "main"?

Just updated the formatted examples on current main.