This is a great and valuable initiative. From my first days with Botan I was constantly confused by the 3 space style and even more by indenting the braces.

I was playing around with the settings a bit and was overwhelmed by the number of possible configurations. Thus I'd vote for adapting an existing style and adjust it for our needs. That way we only need to set values that we have good reason to change which implies that there is a reason for every explicit setting.

Clang format 3.6 (the latest I get from my packages) has 5 default styles: LLVM, Google, Chromium, Mozilla and Webkit. When I tested all of them I found the first 4 too compact for easy reading, which let me to WebKit. Starting with WebKit I noted some things

Pro

• Formatting of multi-line documentation comments (when started with /**)

Con

• Unsymmetrical empty lines at beginning and end of namespace (problem exists with all styles)
• Braces bug in symkey.cpp. Missing linebreak in: OctetString operator^(const OctetString& k1, const OctetString& k2) {
• Indent for inner namespace
• Does not force a max line length

The later two issues can easily be adjusted. I'd go for 100 columns since we're in 2015 and not coding in 80 column command lines. Excessive breaking easily leads to hard to read code.

Given that, my preferred config is

---
BasedOnStyle: WebKit
ColumnLimit: 100
NamespaceIndentation: None
...

The version I proposed was based on the Google version with tweaking. The reason I expanded it out rather than used BasedOnStyleis to make it obvious to a reader who was not familiar with the base style exactly what options were being used and to immunize us from future changes to the Google style. I do see your point on deviations from an accepted style though.

I agree 80 columns is a little tight and in practice many files already have longer lines. I dealt with that in my config by reducing the penalties for excess characters instead, so it would tend to wrap at 80 but would allow longer. But a fixed 100 might be ok also, I'll try it out and see how it looks.

If you think clang-format has a lot of options, check out indent :)

Please!!

There is a problem with 80-column lines already, when printing PDF documentation for Botan. I would be happy to provide examples, where the long lines just run over, making the page less than useful.

So we either need to decide that useful readable documentation is unnecessary - in which case I don’t care what the line length limit is (my screen at the office can accommodate most anything you care to throw at it, really :).

Or we agree that having the ability to print a PDF document describing Botan and serving as a manual is useful - in which case please constrain the number of columns. I assure y’all that it is perfectly possible to write beautiful code without extending a single line beyond, say, column 62.

I’ve meant to bring this up long time ago, but was busy with other things (still am, in fact - but can’t risk the "new” code completely screwing up documentation).

Closing as a PR will reopen as a discussion ticket when I've had a chance to play with clang-format and my emacs cfgs more.

coverage: 90.589%. first build
when pulling e0a521c on reformat-source
into cfb12bf on master.