Formatting

[bcaddy]

Summary

This is where we'll discuss our preferences for a unified formatting scheme in Cholla.

See the Style Wars Discussion for emoji response conventions.

To keep voting organized, make each choice a Comment on the Discussion. The top level Comments should all be voting options or a neutral introduction to the topic. Debates should all happen in Replies: general replies under the neutral introduction, option-specific pros/cons under their vote Comment.

Thus the hierarchy is as follows: Discussions (for each issue), Comments (for each option), Replies (for each pro/con)

Formatting Choices

Here is a selection of code from Cholla, and a default example, of three of the default choices that clang-format comes with. I chose these three to line up with what is being discussed in the naming discussion with the substitution of LLVM for Chromium since the Chromium format was almost identical to the Google format

Code was chosen from Cholla to represent various common cases and those cases are separated by large block comments. I apologize that my own code is overrepresented, some of that is by request of others but mostly I just knew where to find the examples I was looking for in my own code. If there's any piece of code you want to see in any format you can use the clang-format configurator.

current.cpp.txt
google.cpp.txt
LLVM.cpp.txt
mozilla.cpp.txt

[bcaddy]

4 Spaces for Indentation instead of 2

[bcaddy]

I prefer 4 and find it much more readable. They also take up more space and so discourage having long lines and many levels of indentation.

Tabs are of course the ultimate in accessibility but bring with them many formatting issues. Given the ease of changing this later, even if it does generate a TON of diffs I think we should stick to spaces for now.

[evaneschneider]

I strongly prefer 2 spaces, but might be swayed if everyone prefers more.

[alwinm]

We've voted in group discussion to go with 2 for default

[bcaddy]

{ should be on its own line

// i.e. this
void func(args)
{
    stuff
}

// and not this

void func(args) {
    stuff
}

[bcaddy]

I prefer that all scopes/{ have their own line, with the possible exception of namespaces. Scope is a critical component of C++ and so I think that { should be treated as such and have its own line. Many modern IDEs, including VSC, will also draw lines between scope opening and closing, the own-line style works really well with this and the same-line style doesn't.

[alwinm]

This is one I like. Is if/else an exception? Or For loops?

if () { 
} else {
} 

if () 
{
}
else if ()
{
}
else ()
{
}

[bcaddy]

Personally the only exception I would make is namespaces because every style guide had at least that exception.

I actually think that it's even more important for { to have its own line in control statements and loops specifically because those are places that programmers, myself included, would be tempted to add variable declarations that they expect to use after the scope has closed.

// I'm ok with this
if () 
{
} else if ()
{
} else ()
{
}

But I think that if we're putting curly braces on their own lines we should do it everywhere (I also don't know if clang-format will work with that option)

[bcaddy]

We settled on using the "Linux" style

[bcaddy]

Arguments should not be one-per-line

Some styles require that each argument be on its own line in the function definition and/or call. I like this generally for definitions but not for calls. I would also argue that this is made totally irrelevant if we have doxygen documentation for each function since that removes the need for the definition arguments to be easily readable or easy to add comments next to.

[helenarichie]

I've seen style guides recommend one-per-line only if the line exceeds the number of characters allowed per line, which I think is nice.

[bcaddy]

The two methods I've seen with that is either one per line if it exceeds the limit or just wrap arguments to the next line with some kind of indenting. I generally prefer the latter since I think it makes it easier to track multiple, similar calls.

[bcaddy]

Votes for Google C++

[bcaddy]

I vote for this. It looks just like LLVM to me but I've generally found Google's style documentation to be more complete and easier to read. Plus it looks like we're basing our naming convention off of Google so it would be nice to be consistent

[bcaddy]

Votes for Mozilla C++

[bcaddy]

I don't like this one. The mandated "one argument per line" in function calls makes it hard to read when there are multiple similar calls, which we have a lot of.

[bcaddy]

Votes for LLVM C++

[bcaddy]

Looks just like Google to me. I've generally found Google's style documentation to be more complete and easier to read though.

[bcaddy]

Long Comment Lines for Separation

Lines like this to separate functions

// ===================================================================
void func1(args)
{
    stuff
}
// ===================================================================

// ===================================================================
void func2(args)
{
    stuff
}
// ===================================================================

[bcaddy]

A lot of my code has long comment lines that look the above this to visually separate functions because I find it much easier to read. I don't think that we should mandate this but does it bug anyone?

[alwinm]

Doesn't bug me, glad to have some optional things we don't mandate 👍

[helenarichie]

I'm honestly not crazy about it, but as long as it's not mandated that's fine by me!

[bcaddy]

Consecutive Assignments Should be Aligned

// This
int aaaa = 12;
int b    = 23;
int ccc  = 23;

#define SHORT_NAME       42
#define LONGER_NAME      0x007f
#define EVEN_LONGER_NAME (2)
#define foo(x)           (x * x)
#define bar(y, z)        (y + z)

// Not this
int aaaa = 12;
int b = 23;
int ccc = 23;

#define SHORT_NAME 42
#define LONGER_NAME 0x007f
#define EVEN_LONGER_NAME (2)
#define foo(x) (x * x)
#define bar(y, z) (y + z)

[bcaddy]

Having a block of assignments is common at the beginning of functions and in Cholla in general. IMO having them aligned is more readable. clang-format supports several variants of this, I just posted my favorite.

[helenarichie]

If it were automatically enforced with clang-format I could get on board, since my only objection would be that it's kind of hard to format by hand

[bcaddy]

you can enforce it with clang-format. There's a bunch of different options and sub options but what I have above is my preferred option.

[bcaddy]

We decided to have things aligned

[helenarichie]

See the Cholla Wiki for a summary of this discussion: https://github.com/cholla-hydro/cholla/wiki/Making-a-Pull-Request