[Conventions] Define further conventions

[kevinmatthes]

In order to prepare an active contribution to the project, I would like to know more about the applied conventions. By doing so, I intend to keep a uniform look of the repository when contributing.

Since CONVENTIONS contains only information about the name mangling procedure at the moment, I would like to suggest to add further conventions thereby in this file. As an enhancement for a future version, one might also think about adjusting all source code to meet the requirements of CONVENTIONS such that contributing as well as overall orientation within the code becomes easier due to reliable standards.

[kevinmatthes]

One of the most important questions is the matter of spacing and indentation.

Despite the common question of tab versus spaces, there are also possible differences regarding the framing of operators and operands by spaces, e. g.

int a=0x0+0x1;     // No framing at all.
int b = 0x0 + 0x1; // Always appropriate framing.
int c = 0x0+0x1;   // Only sometimes framing.

By looking at the overall formatting of the repository, I noticed that

• indentation is done by spacing, by default.
• the indentation range is 2, i. e. indentation is processed by 2 spaces, mostly.
• operator spacing is mixed at the moment.

Are these impressions correct and according to the current conventions or should other methods be applied for future code?

[michaelquellmalz]

I think the indentation with 2 spaces and the framing could be part of the conventions for future code. The framing probably is mixed between the second and third variant, so I would probably prefer the second, but the third is also okay. The first one is really bad for doing find&replace.

[kevinmatthes]

Okay, I am going to add these things to CONVENTIONS. I would thereby suggest to rename it into contributing.md since the information concern the way how to work on the project, as well.

The next thing I would like to discuss is the general style. Here is an overview over three common styles:

// K&R.
int foo_1(int x, int y, int z)
{
  if (x < foo(y, z)) {
    var = bar[4] + 5;
  } else {
    while (z) {
      var += foo(z, z);
      z--;
    }
    return ++x + bar();
  }
}

// BSD.
int foo_2(int x, int y, int z)
{
  if (x < foo(y, z))
  {
    var = bar[4] + 5;
  }
  else
  {
    while (z)
    {
      var += foo(z, z);
      z--;
    }
    return ++x + bar();
  }
}

// GNU.
int foo_3 (int x, int y, int z)
{
  if (x < foo (y, z))
    var = bar[4] + 5;
  else
    {
      while (z)
        {
          var += foo (z, z);
          z--;
        }
      return ++x + bar ();
    }
}

I would suggest the following style, a mixture of GNU and BSD:

int foo_4 (int x, int y, int z)
{
  if (x < foo (y, z))
    var = bar[4] + 5;
  else
  {
    while (z)
    {
      var += foo (z, z);
      z--;
    };
    return ++x + bar ();
  };
}

Style 4 has proven to be quite good readable.

Furthermore, there is the question how to break very long tuples, e. g. from parameter lists. I would like to propose the Haskell-like style which forms some sort of bulleted of the parameters:

void foo ( const int a
         , const int b
         , const int c
         , const int d
         )
{
  return;
}

[michaelquellmalz]

I would also prefer style 4 (which seems to be in line with most of the code). However, I think we could delete the semicolons in }; before and after the line return ++x + bar ();. The line-breaking is also okay with me.
In general, we should write this conventions for additional code, I am not sure if modifying existing one just for the style is necessary.

[tvolkmer]

The newer code should be mostly BSD style 2 which would be my preferred choice.
Moreover, I would vote against a semicolon in };

In any case, we should only reformat code that is modified. Otherwise, it would be hard to distinguish between code changes and formatting changes.

[kevinmatthes]

I agree with both of you that the changes should be made first of all to newly adjusted lines of code. For the big update to version 4.0.0, I would suggest anyway that such a refactoring should be processed for all source files but this is an optional change.

I am going to add the concerning information to CONVENTIONS. I would suggest that the contributing should use mostly the BSD style with some mixture with GNU as style 4 shows, if desired.

[kevinmatthes]

What about the Haskell style of line breaking?

[kevinmatthes]

• Haskell line breaking is recommended for longer parameter lists
• const: West Const
• table structure should rather not be used for declaration lists
• declarations should be made one variable per line
• no tab stop characters, i. e. \t
• void functions may contain return statements
• void parameter lists may contain the void key word
• the English variant (e. g. British English, US American English) should be chosen and applied individually and consistently
• no gotos!
• type annotations shall use upper case letters and should be used whenever possible
• * of pointers belong rather to the identifier of any symbols (variables and functions) and should not be separated with any separators
• struct pointer operators (->) should rather not be separated with any whitespace characters from neighbouring symbols
• if, for and while should be followed by spaces
• function identifiers should not be followed by spaces
• sequences with the same meaning shall be separated by a single blank line from neighbouring sequences; the same holds true for statements with blocks (if, for, switch)
• all internal functions should be flagged static
• typedefs should be rather defined within a preprocessor protection block (#ifndef ... #define ... #endif)
• macros should be rather short and simple (one line of code)