Initial clang-format file

[j-stephan]

This is a first proposal for the clang-format file along with a set of rules written in Markdown.

[update psychocoderHPC]
Please read #39 (comment) before you start to comment on this PR.

[bernhardmgruber]

I actually never had a problem with line endings, because git handles this automatically. So I wonder if we need to set anything here. I am afraid that it could mess up when formatting on Windows machines.

[psychocoderHPC]

Line endings depends on your git configuration. IMO if we enforce it we will avoid issues.

[bernhardmgruber]

So far this does not seem to be an issue on Windows.

[BenjaminW3]

+1

[bernhardmgruber]

Ok, this turned out to be an issue for Windows now. Given a file with sections where clang-format is disabled:

    ...
    // clang-format off
    ...
    // clang-format on
    ...

Git by default will checkout with CRLF on Windows as it should. When you clang-format now, all lines are switched to LF, EXCEPT the lines where clang-format is disabled. This results in a file with mixed line endings and some IDEs rightfully complain now. Formatting the entire file using LF solves the IDE problem but then shows the entire file as changed in git.

[j-stephan]

I am now wondering if we shouldn't enforce the correct line ending through git rather than clang-format. This should prevent the issues described by Bernhard.

[bernhardmgruber]

This contradicts the argument made above to not overuse whitespace. Also many IDEs and editors offer nice block scope guides:

I would like to hear a stronger rational for Allman style. And I would like vote for a style that keeps the opening brace on the same line ;)

[jkelling]

I think the given **Reason** is correct, but one could elaborate on why it is better at optically separat[ing] different scopes: The K&R example you show would indeed not be improved much by Allman, but K&R breaks down when the block opening statement needs to be broken to the next line:

if ( something(somethingElse) < moreElse 
    && something(somethingElseElse) > 0) {
    doSomething();
}

The Java Variant also breaks down for constructors, which happens more often:

ClassName::ClassName(Type a, ....)
    : m_a(a), /*more things here so this cannot be inline*/.. {
    m_b = f(a);
}

Granted, this could be worked around by having ContinuationIndentWidth > IndentWidth and ConstructorInitializerIndentWidth > IndentWidth, respectively, but this is not currently proposed, and would also feel strange to me.

Not sure if the

struct Name {

in your example is the Java variant, or either, but this gets into the same trouble when a list of base classes is added.

[bernhardmgruber]

I started out aligning everything as well, but I ran into cases where it was not visually pleasing:

for () {
  ...
  someLongVariableName += 1;
  result                = thisIsAFunctionCall(withSomeArguments, andAnother);
  i                    += offset;
}

It happens ;) So I started to be more defensive here. But find out yourself ;)

[sbastrakov]

I am not very emotional on this one, as it does not happen often, but to me such alignments feel very bad, or to mirror the reasoning text visually ugly

[jkelling]

Alignments are bad because they are not invariant under refactoring, i.e. if you change the length of the longest variable name (or add a new longer one) all the others need to change, too.

In addition tom this, I think, prescribing alignment is only an option if we could configure a pre-commit hook running a fixer. I would not want to spent half my time coding aligning things, or fighting with my editor if it is configured to do this automatically.

[BenjaminW3]

Alignments are bad because they are not invariant under refactoring, i.e. if you change the length of the longest variable name (or add a new longer one) all the others need to change, too.

I totally agree. Alignment leads to unnecessarily large diffs. Especially with short line length, parameters to functions, templates, etc. are often on multiple lines. If you rename a function, template, etc., then all the parameters in all invocations have to be realigned as well.
This is the reason why the proposed alpaka style had all alignments disabled:

I am ok with the options below but I dislike the AlignAfterOpenBracket option.
I would prefer if the above example would look like:

auto some_long_function(
    argument1,
    argument2);

especially when you have multiple methods in a header, the aligned style looks very noisy while the indentation makes this look clean.

[bernhardmgruber]

I just tried the suggested .clang-format file on LLAMA. I am not sure if I like this one:

    constexpr std::size_t hardwareThreads = 2; // relevant for OpenMP2Threads
    using Distribution                    = common::ThreadsElemsDistribution<Acc, BLOCK_SIZE, hardwareThreads>;
    constexpr std::size_t elemCount       = Distribution::elemCount;
    constexpr std::size_t threadCount     = Distribution::threadCount;
    constexpr FP ts                       = 0.0001;

This one turned out nice:

constexpr auto DEFAULT_IMG_X   = 4096; /// width of the default image if no png is loaded
constexpr auto DEFAULT_IMG_Y   = 4096; /// height of the default image if no png is loaded
constexpr auto KERNEL_SIZE     = 8;    /// radius of the blur kernel, the diameter is this times two plus one
constexpr auto CHUNK_SIZE      = 512;  /// size of each chunk to be processed per alpaka kernel
constexpr auto ELEMS_PER_BLOCK = 16;   /// number of elements per direction(!) every block should process

I do not like this one:

        int x               = 0;
        int y               = 0;
        int n               = 3;
        unsigned char* data = stbi_load(argv[1], &x, &y, &n, 0);

I feel like I am weakly against alignment. Also the reasons given by others, like larger diffs, make me feel aligning is not a good idea.

[steindev]

See vote (#39 (comment))

[bernhardmgruber]

I would turn that into: Use goto sparingly. Or just reference the C++ core guidelines: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-goto

[psychocoderHPC]

Since code style based on own opinions it is hard to find a con-sens.
Therefor I will apply some rules to this PR else there will be the question who is selecting the final value for the style option.
We introduce a voting system as described in this post.

To be clear, after we have a common code style the style file will be pushed to all our projects, including PIConGPU, cupla, alpaka, ...

Rules

• Use direct comment instead of the grouped review feature.
• Do not comment that you like or dislike something if you do not like to change an option or vote. (This reduce the number of comments)
• If you dis-like an option start a vote

Voting:

• if you like to change an option open a vote with the following template:

**VOTE**
current | <option1> |
--------|-----------|
 0      |   1

<long description why you like to change it or why you voted how you voted>

• Everyone can only vote once!
• Everyone who votes is increasing the value in the column he likes.
• If you changed you opinion you comment again and reduce the column value you set by 1 and increase an other column.
• If you like to set an other value than in the voting options than add a column.
• At the moment where someone starts a vote everyone has 5 days to vote until the final value will be fixed set
• If there is a race in the votes because two users start voting at the same line I will fix the counting with my admin power
• If two voting options will have the same count after 5 days I will ask everyone to rethink his opinion (hope this solves such situation)
• @j-stephan do not push changes to this PR
• If there is for 5 days no new voting request, @j-stephan or me provide a new PR where all options will be set to whatever was winning the vote. This PR will than be used that everyone can have a final look to it. Already voted option will not votable again except someone provides code where an option is fully destroying the style.

Example

• USER1 not like the 79 char line length he/she starts

**VOTE**
current | 120 |
--------|-----------|
 0      |   1

I think 120 is fitting current monitors better

• USER2

**VOTE**
current | 120 |
--------|-----------|
 1      |   1

I think a three way diff requires short lines

• USER3

**VOTE**
current | 120 | 140 |
--------|-----------|---|
 1      |   1       | 1    

Come on we need longer lines

• USER 1 is changing is opinion

**VOTE**
current | 120       | 140 |
--------|-----------|---|
 1      |   0       | 2    

Ohh USER2 is right, I like the suggestion

• 5day's later

**FINALIZED**
option will be changed to 140

If you thing someone should attend this code style finding process please provide the link of this PR to him/here.

CC-ing: @ComputationalRadiationPhysics/picongpu-developers @ComputationalRadiationPhysics/alpaka-developers

[BenjaminW3]

I had a bad experience with this option together with ReflowComments and short line lengths. Hopefully this has been fixed.

[j-stephan]

I like the format proposed by @psychocoderHPC. In addition I suggest that anyone who starts a vote also needs to supply an accompanying change to guidelines.md as part of the vote.

[j-stephan]

Please also note the separate vote in #40.

[bernhardmgruber]

Since the interval ended for several votes this weekend, I prepared a new .clang-format file and ran it on the current develop of LLAMA. Here is the result: https://github.com/ComputationalRadiationPhysics/llama/pull/103/files

[j-stephan]

There are no more open votes. If there won't be any new votes until Friday I will close this PR - all options not voted for will have their current values then.

[jkelling]

I opened another vote, which apparently went unnoticed: about tabs.

[j-stephan]

There are no more open votes. If there won't be any new votes until Friday I will close this PR - all options not voted for will have their current values then.