Skip to content

remove obsolete section about code formatting, explain clang-format better #1136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

remove obsolete section about code formatting, explain clang-format better #1136

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
269ce74
remove obsolete section about code formatting, explain clang-format b…
silverweed Jul 7, 2025
86499f2
add a brief section to explain the coding style choices
silverweed Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 30 additions & 104 deletions contribute/coding_conventions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,123 +98,49 @@ Note the mandatory method separator line:
{% endhighlight %}
exactly 80 characters long.

## Preferred Coding Style
Here we describe our preferred coding style. Coding style is very personal and we don't want to force our views on anybody. But for any contributions to the ROOT system that we have to maintain we would like you to follow our coding style.

### Indentation
To be able to keep as much code as possible in the visible part of the editor of to avoid over abundant line wrapping we use indentation of 3 spaces. No tabs since they give the code always a different look depending on the tab settings of the original coder. If everything looks nicely lined up with a tab setting of 4 spaces, it does not look so nicely anymore when the tab setting is changed to 3, 5, etc. spaces.
Comment on lines -101 to -105
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider keeping those 2 non-tool specific paragraphs.

Copy link
Contributor Author

@silverweed silverweed Jul 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first may still be useful indeed, but the second is completely handled by the formatter, no? (meaning that if we enforce the use of clang-format the user doesn't really have a choice on tab vs spaces)

Copy link
Member

@pcanal pcanal Jul 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True but clang-format is not yet (there is hope though) fully supporting the 'real' formatting we want (see in particular the alignment in the header files), consequently we still need to leave the clang-formatting optional and thus some unwanted formatting will still be committed. Most formatting are harmeless-ish and can be most hand done ... the tab vs space is extremely (slight exaggeration) annoying (to me) and can be invisible to (newer) developers, so I would keep it.

On a different note, there is a slight question on whether it is helpful to describe the general/main formatting choices so developers get used to typing it almost correct ... or not. (but we definitively can not expect developers to read the clang-format to know the rules (the .clang-format is too dense and long) ... on the other hand the existing might be a (close enough?) documentation/example)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it is good to give developers an overview of the main formatting choices and their rationale; on the other hand the use of an automated formatter should have the main goal of relieving them from having to spend time thinking about it. What about keeping the paragraphs but placing them below the clang format description? And make it clear that if all they care about is submitting "valid" code they can skip them but if they want more details they can optionally read them...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, reordering in this way sounds fine.


### Placing Braces and Spaces
The other issue that always comes up in C/C++ styling is the placement of braces and spaces. Unlike the indent size, there are few technical reasons to choose one placement strategy over the other, but the preferred way, as shown to us by the prophets Kernighan and Ritchie, is to put the opening brace last on the line, and put the closing brace first, thus:
{% highlight C++ %}
if (x is true) {
we do y
}
{% endhighlight %}

However, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus:
{% highlight C++ %}
int function (int x)
{
body of function
}
{% endhighlight %}
Functions are special (you can't nest them in C/C++).
Note that the closing brace is empty on a line of its own, **except** in the cases where it is followed by a continuation of the same statement, ie a `while` in a `do`-statement or an `else` in an `if`-statement, like this:
{% highlight C++ %}
do {
body of do - loop
} while ( condition ) ;
{% endhighlight %}
and
{% highlight C++ %}
if (x == y) {
...
} else if (x > y) {
...
} else {
...
}
{% endhighlight %}
## ClangFormat
ClangFormat is a Clang tool which allows you to format your code. All new contributions to the ROOT codebase **must** be formatted with the repository's clang-format style.

Note that this brace-placement also minimizes the number of empty (or almost empty) lines, without any loss of readability. Thus, as the supply of new-lines on your screen is not a renewable resource (think 25-line terminal screens here), you have more empty lines to put comments on.
Here is how to format your code with ClangFormat:

Notice also in the above examples the usage of spaces around keywords, operators and parenthesis/braces. Avoid the following free styles:
{% highlight C++ %}
if (x == y) {
{% endhighlight %}
1. install `clang-format` from your package manager (or downloading the executable if you're on Windows);
2. after you finished writing your code:
```
git add <my_code>
git clang-format # formats only the new code added
git add <my_code> # adds any modifications done by clang-format
# ... git commit and all the usual ...
```

or any derivative thereof.
ClangFormat should pick up the proper style to use from the `.clang-format` file in the [ROOT GitHub repository](https://github.com/root-project/root/blob/master/.clang-format).

## ClangFormat
ClangFormat is a Clang tool which allows you to format your code.
Most code editors allow you to integrate clang-format directly while writing code (e.g. with format on save). This is handy, but you must make sure that you don't format other previously-present code while doing so: otherwise your commit will contain a mix of formatting changes and "real" changes.
If you want to do this, *first* format the document and make a commit with only the formatting changes, *then* add your new changes.

You can find the `.clang-format` file with the ROOT style in the [ROOT GitHub repository](https://github.com/root-project/root/blob/master/.clang-format).
### About the coding style
***NOTE**: this paragraph is for people interested in the choices over the coding style. If all you care about is having proper formatting, clang-format will automatically apply all the rules described here.*

## Astyle
If you don't have access to ClangFormat, [astyle](https://astyle.sourceforge.net/){:target="_blank"} can be useful. Starting from a code like this:
Coding style is very personal and we don't want to force our views on anybody. But for any contributions to the ROOT system that we have to maintain we would like you to follow our coding style.

{% highlight C++ %}
int aap ( int inp ) {
if ( inp > 0 ) {
return 0 ;
int a = 1 ;
if ( inp == 0 && a == 1 ) {
printf ( >"this is a very long line that is not yet ending" , a, inp, a, inp, a , inp ) ;
a + = inp ; return a ;
}
} else {
return 1 ;
}
if ( inp == 0 )
return - 1 ;
return 1 ;
}
{% endhighlight %}
#### Indentation
To be able to keep as much code as possible in the visible part of the editor of to avoid over abundant line wrapping we use indentation of 3 spaces. No tabs since they give the code always a different look depending on the tab settings of the original coder. If everything looks nicely lined up with a tab setting of 4 spaces, it does not look so nicely anymore when the tab setting is changed to 3, 5, etc. spaces.

You will find back like this:
#### Braces and spaces
The styling of braces and spaces follows the Kernighan and Ritchie rules: statements have their opening brace on the same line, whereas functions have it on the next line:
{% highlight C++ %}
int aap (int inp) {
if (inp > 0) {
return 0 ;
int a = 1 ;
if (inp == 0 && a == 1) {
printf ("this is a very long line that is not yet ending" , a, inp, a, inp, a, inp ) ;
a + = inp ; return a ;
}
}
else {
return 1 ;
}
if (inp == 0)
return - 1 ;
return 1 ;
if (x == y) {
doY();
}
{% endhighlight %}

Get at least version 2.0 and use the following `~/.astylerc`:

{% highlight C++ %}
# ROOT code formatting style
# Note that the brackets=linux option is not available starting from astyle 2.04
#brackets=linux
style=stroustrup
mode=c
align-pointer=name
indent=spaces=3
indent-switches
indent-cases
indent-namespaces
max-instatement-indent=40
indent-preprocessor
convert-tabs
pad-header
pad-oper
unpad-paren
int function(int x)
{
body of function
}
{% endhighlight %}

## Using ClangFormat or Astyle in your preferred editor
Some code editors/IDE can make use of `clang-format` or `Astyle`. For example `QtCreator` has a [plugin for clang-format](https://doc.qt.io/qtcreator/creator-beautifier.html){:target="_blank"} and the `Visual Studio Code Editor` has also a couple of `clang-format` and `Astyle` extensions.
Rationale: it minimizes the number of empty (or almost empty) lines, without any loss of readability. Functions are special (you can't nest them in C/C++) so they get an exception to the rule.
Also notice that all statements have a space before the opening parenthesis, but function names and function calls don't.
There is no hard rule for placing braces around single-statement blocks (e.g. for and `if` with a body consisting of a single line). Use your judgement.

## Where to go from here
For the rest read the
Expand Down
Loading