Ok, I have written an initial version. I'd like to send this in for review soon, but want to first give all of you a brief opportunity to respond. Preferably we can finish this without going through another round of RFC. For changes see the PR.

Paul Price, Russell Owen and Jim Bosch had some comments on the PR.

As far as I can tell there are only two remaining issues.

1. What do we do with things not covered by clang-format? I would argue that these are out of scope for now and should simply be done manually.
2. How (if at all) should clang-format be made available to developers? Should we provide instructions to install it? Or even a package? I would argue that we should simply point to upstream installation instructions, given the fact that everyone has their own preferred way of installing and use of clang-format is not mandated.

Note that after much discussion in various places (RFC, PR, Community) the current implementation of this ticket replaces section 6 (concerning code layout) of the DM C++ style guide with the following two rules:

• 6-1. Layout SHOULD follow the rules from the formatting section of the Google C++ Style Guide (with a few exceptions).
• 6-2. Layout MAY be automated with clang-format.

The exceptions being 110 column width with 4 space indentation. This is roughly equivalent to what was done with the DM Python style guide switching over to be PEP8 based.

What do we do with things not covered by clang-format? I would argue that these are out of scope for now and should simply be done manually.

I assume these are things covered by the modified Google layout, but not implemented by clang-format, rather than things covered in the (non-layout) rest of our coding conventions? If so, it might be worthwhile to list the most common things in the dev guide, to warn developers that they can't rely on clang-format for everything. Of course, we may need to build up this list incrementally as we notice things.

How (if at all) should clang-format be made available to developers? Should we provide instructions to install it? Or even a package? I would argue that we should simply point to upstream installation instructions, given the fact that everyone has their own preferred way of installing and use of clang-format is not mandated.

I think I generally agree that pointing at upstream installation instructions makes the most sense. Trying to have a "recommended" install for the most common platforms (and maybe editor integrations) seems like a good idea.

It would be helpful to explicitly list the recommended configuration parameters for clang-format.

From reading http://clang.llvm.org/docs/ClangFormatStyleOptions.html we certainly at least need:

BasedOnStyle: Google

IndentWidth: 4

ColumnLimit: 110

I wonder if we will need any others? Some possibilities include:

ConstructorInitializerIndentWidth: 4

ContinuationIndentWidth: 4  # continued lines will indent to match an open bracket by default, but what about other cases?

TabWidth: 4  # unlikely because we don't use tabs

Jim Bosch

I assume these are things covered by the modified Google layout, but not implemented by clang-format, rather than things covered in the (non-layout) rest of our coding conventions? If so, it might be worthwhile to list the most common things in the dev guide, to warn developers that they can't rely on clang-format for everything. Of course, we may need to build up this list incrementally as we notice things.

I don't know of any things in the formatting section not covered by clang-format. Then again, I haven't tested every rule in detail. I agree we should just tackle these things if and when they come up.

I think I generally agree that pointing at upstream installation instructions makes the most sense. Trying to have a "recommended" install for the most common platforms (and maybe editor integrations) seems like a good idea.

Ok, but what are the "most common platforms"? OSX and Linux I assume. But which version of Linux? Which editors? Do we have some convention for this? And is the style guide the best platform for this? Perhaps this belongs in "workflow" or even on community?

Russell Owen

It would be helpful to explicitly list the recommended configuration parameters for clang-format.

I'm not sure we need others. I think we should only list those that are explicitly different from the Google style defaults. If we need any others, we can always add them. I'll check the ones you suggested.

Ok, but what are the "most common platforms"? OSX and Linux I assume. But which version of Linux?

I'd suggest some (brief!) wording along the lines of "clang-format may conveniently be installed using a package manager on most common operating systems. Look for the package named xxxx on CentOS or yyyyy on Ubuntu. On macOS we suggest Homebrew (package name zzzz)."

Which editors?

The clang-format documentation already includes material on editor integration. I don't think we need do any more than that in terms of core documentation...

Do we have some convention for this? And is the style guide the best platform for this? Perhaps this belongs in "workflow" or even on community?

...but I'd be happy to see devotees of particular editors, workflows, etc post their tips to clo.

Regarding clang-format configuration:

It turns out we cannot safely allow clang-format to reorder includes, due to the some subtlety of header files for Python C extensions (Jim Bosch understands the issues; I don't). Setting config parameter SortIncludes false is apparently supposed to stop this. However, I have not gotten it to work using the Clang Format plugin for Sublime Text. So we should be extremely careful of this before running an automated clang-format pass on our code, lest we break something.

Another config parameter to consider is IncludeCategories; we might be able to use this to enforce our desired grouping of include files. It is a sequence of regular expressions and I have not played with it.

I used IncludeCategories before. It works well. You basically supply a list of regexps with placement priority. Every include in a group (delimitated by a blank line) is then sorted accordingly.
However, this may of course still break things (and probably will) if the includes happen to depend on their current ordering.

One might conclude however that includes depending on ordering is a bug that should be fixed anyway.

I have updated the DM guide as follows:

• Created a new tools/clang_format.rst chapter and moved instructions there;
• Added emacs and vim integration to their respective sections in the guide;
• Added the SortIncludes: false option.

Kian-Tat Lim Given the result of RFC-107 should we also change the rule for C++ to be the Google default of 80 column line limit? Or do we stick to 110 here?

My understanding is that the tools for processing C++ are such that no decision on a change to the C++ line length is necessary at this time. As a result, we stick with the status quo.

Pim Schellart [X] Kian-Tat Lim C++ tends to need longer lines than Python (e.g. due to templating) so I fear that reducing the line width to 79 chars would make it less readable. Having auto and clang-format helps, but they can only do so much. That said, I'm somewhat on the fence because for the editors I've used, it is significantly easier to configure an editor for one set of settings for one language, rather than different settings for different languages.

I second Russell's objection. I expect that 80-character lines will lead to a lot of multi-line statements, particularly declarations.

The comments are noted. We are not shortening C++ lines any time soon.

Ok, I have no objections to that
The text will be merged as as is, as soon as Kian-Tat Lim signs off on it (assuming no further comments arise).

Is this safe to use yet? Would be nice for pybind11.

Kian-Tat Lim is there a specific issue blocking the merge?

Pim Schellart [X] I'd say on new code there's no damage running it given how much of our existing code does not conform. At least it will get it close.

The specific issue is whether anything in the Google style guide would be a required change from our current style guide. The only way I could figure out to determine this was to critically read through both sets and do a comparison, which was taking more time than I had available. If someone could reassure me on that, it would help.

Oh, also it wasn't clear if there were any of our previous style guidelines that would disappear with the new rules. It would be good to summarize that as well.

Ok, given the need for a diff I went with a different approach. Instead of adopting the Google C++ Style Guide (layout section) wholesale (which would require some mental gymnastics for users translating between different spacing and naming conventions) I updated our existing rules to compatibility with the Google (and clang-format) layout rules.

This should serve the primary goal of being able to use clang-format and keep as much of our existing style guide as possible. Perhaps Jim Bosch and / or John Swinbank want to take a look at it before I send it back to Kian-Tat Lim for approval?

A couple of open questions:

• Spaces around *, / and % are preferred but optional in the Google C++ Style Guide (clang-format always puts them in and this is not configurable). What do we do? As currently worded in the update they become optional too such that both old and new style are allowed. Which probably means it will gradually evolve to use spaces over time as people apply clang-format to files they are working on.
• Currently class layout uses Google rules for indentation, scaled up by a factor of two (to four spaces). This looks mostly identical to our old rules, except that access specifiers are now offset by two spaces. We could easily not offset them too if that is preferred. Note that the offset doesn't introduce any extra indenting to the code (see examples).
• We have no rules for a lot of things: initializer lists, placement of & or *, lambdas, etc. clang-format does make choices here. However I assume we stick to not naming rules for these explicitly?

And finally, I noticed a few cleanup actions that we may want to do, but perhaps on a separate ticket?:

• Add missing quotes around code in text (sometimes they are used, sometimes not looks like typo's)
• Renumber rules? Right now, rules are numbered across sections which makes it impossible to add rules to an existing section.
• Remove deleted / empty rules?

Perhaps Jim Bosch and / or John Swinbank want to take a look at it before I send it back to Kian-Tat Lim for approval?

Do you think that's necessary? I'm not motivated to do this unless it'll help you.

John Swinbank feel free to ignore.

I haven't looked in detail at the changes, and I don't think I care enough about the subject to do so unless you want another pair of eyes on it before K-T. In general, anything we can do to keep from making old code that was conforming becoming nonconforming with the new rules would be good.

One thing I do care a bit more about: I'd like to avoid having access specifiers (or anything else) with an indent level smaller than 4 spaces - that can confuse some editors (e.g. SublimeText) that try to infer the tab width from the file.

Ok, I'll set the access specifiers to -4 spaces (i.e. back to our old convention), squash the commits and give the whole thing a final glance before sending it off.

Kian-Tat Lim Ok, I think it is ready.

Two minor notes. Pim Schellart [X] has already said this, but I hope we are willing to allow spaces around * and / because I think clang-format will insist on it. Also, clang-format in google style does unpredictable things with &, e.g. it sometimes adds a space afterwards and sometimes does not, and it may break a line between the & and the next item (I noticed this often when formatting pybind11 wrappers). I am not complaining or saying we should change anything, I am just hoping our standards will be loose enough to tolerate these issues. I am very much in favor of automatic formatting!

We will have to allow spaces, otherwise we cannot use clang-format, but the question is do we make them optional or mandatory?

As for the `&`, clang-format follows the Google rules, which allows it to be attached either to the type or the variable. I don't think we have any rule that conflicts with this behaviour.

Relatively minor suggestions on the PR. I'm sorry this has taken a long time, but I hope people are reasonably pleased with the result.

Merged after changes.
Thanks! I'm very happy that I can now use clang-format!