Mixed tabs and spaces

[myTonino]

Most source files contain a mix of tabs and spaces that renders in editors tab width different than 4 strangely. This is also the case on viewing the files online here on Github and applies also to the mesh and networking lib.

[Avamander]

If you have the time to reformat all files according to NASA's C style guide then you could submit a pull request and I'll merge it.

[wmarkow]

@Avamander, do you know some kind of source formatter (beautifier) software that would be able to format the code according to NASA C style? I have searched the Internet but I wasn't able to find such a software. I could find the only the docs related to the style:

• NASA C Style
• NASA C++ Style

During my standard Arduino development I'm using Eclipse CDT with Sloeber Plugin. Eclipse CDT is able itself to format the code, by default only according to the following rules:

• K&R
• BSD/Allman
• GNU
• Whitesmiths

@Avamander, could you please write shortly why you prefer NASA C Style? Or what are pros for using NASA? I know that the code style treats about the "visual view of the code" (like the number of spaces in the indentation, the braces, where to put a new line and so on) but also it gives some clues about how to name correctly the functions, variables, and so on.
NRF24 uses C++ so we would need some style guide related to C++ as well. Above I have put two link, the second one refers to NASA C++, I just found it in the Internet but I'm not quite sure if this is still valid. What are your thoughts?

[Avamander]

@wmarkow It's both well written down, used in mission-critical places (thus one can say it's field-tested to be at least okay) and it most closely resembles what people write and what's used currently in the library.

If you have better suggestions, feel free to comment them, and yeah, C++ style guide probably suits us more (and you probably can switch your IDE to Allman style as it's really close).

[MAKOMO]

I am not even a C programmer, but I could assist in just replacing tabs by 4 spaces in all .h and .c files. That would increase readability on Github via a Web browser as well as editors that render tabs with a number of spaces different from 4. Let me know.

[wmarkow]

Thanks @MAKOMO but we can make the process automatic. I'm using Eclipse CDT for Arduino development. Eclipse has embedded code formatter. It is possible to create your own formatting rules, so I have created a formatter according to this NASA C++ guide.

I have formatted two files with this formatter. There are commited in my RF24 fork in my fix_for_#391 branch.
I think there is something still missing in this formatter (like I have noticed that preprocessor commands sometimes are not formatted correctly). Most basic thing: I have put 3 spaces (NASA recommends strongly that) in the indentation. But we can use 4 spaces as well - I think.

@Avamander, could you please take a look at my branch and make a short review? Thank you for your comment related to coding styles. I took a look and indeed you were right; Allman style is quite close to NASA. When I started to learn C/C++ many years ago I was taught some good coding styles but I didn't know that it was according to NASA. I like NASA coding style :)

One more thing: if we decide to use this code formatter then it is better to take a look at the pull requests first and merge them before we format the code (we will avoid many merge conflicts that will be an effect of code formatting).

And we could fix manually the #385, I mean to put the braces into one line if statements.

[MAKOMO]

@wmarkow: please go forward with this. 3 or 4 spaces are ok for me, just tabs should be avoided. I also agree that it might be easier to process pull requests first. The same work should also be applied to the Networking and Mesh lib.

[Avamander]

@wmarkow Your branch looks okay. Though the Arduino examples should be formatted with the Arduino IDE, should just be kept in mind when that bridge is to be crossed.

Pull requests can usually be updated by other people (thus formatted too), if not opening a new one with the good style (without conflicts) would be totally okay imho.

Another thing that should be done is a short description of the formatting style in the CONTRIBUTIONS.md and PULL_REQUEST_TEMPLATE file just to let people know it's established how to contribute code.

[wmarkow]

I took a look at Arduino IDE 1.8.5 and how its formatting works. To auto format the code in Arduino IDE just hit Ctrl + T (or choose Tools->Auto Format). This autoformat works strange. It looks like it doesn't care about "brackets". This piece of code is formatted "correctly" with Arduino IDE:

void setup()
{
  // initialize digital pin LED_BUILTIN as an output.
  pinMode(LED_BUILTIN, OUTPUT);

  int  a = 5;
  if (a == 5)
  {
    a = 4;
  } else if (a == 3) {
    a = 2;
  }
}

I noticed that mostly it takes care about 2 spaces indentation and it put some spaces where needed.

Now I'm just thinking that the Built-In Examples in Arduino IDE are the clue on what is their favorite code style (formatting).

[Avamander]

@wmarkow So you think we should format everything with the Arduino IDE?

[wmarkow]

No, I think we can stick to the NASA format as you suggested before.

Though the Arduino examples should be formatted with the Arduino IDE, should just be kept in mind when that bridge is to be crossed.

I just wanted to check what is the default formatting style in Arduino IDE but it looks like it allows some mixed formatting styles and actually you need manually take care of putting the brackets in a proper format.

[per1234]

I think wmakow has the right idea with the example sketches: Follow the Arduino IDE's Tools > Auto Format conventions and then use the official Built-in Examples (and code from the Language Reference pages or other official code where that doesn't suffice) as a reference for any formatting choices not set by Auto Format. This is the style that Arduino users are comfortable with seeing in sketches.

The Arduino IDE uses AStyle for the Auto Format. The stock configuration is here:
https://github.com/arduino/Arduino/blob/master/build/shared/lib/formatter.conf

AStyle also allows you to configure more formatting options, as documented here:
http://astyle.sourceforge.net/astyle.html

I believe that adding the following options to the Arduino IDE's current AStyle configuration file will fully enforce the Arduino formatting style:

style=attach
break-closing-braces
attach-closing-while
attach-extern-c
add-braces
align-pointer=name
convert-tabs

Note that some of these AStyle configuration options require a newer version of AStyle than is used by the Arduino IDE. The version of AStyle used by the Arduino IDE does not permit formatting to Arduino style braces because break-closing-braces and attach-closing-while (which are not supported by that version) are required in addition to style=attach (which is supported).

Even though it's in the stock Auto Format configuration, I would suggest removing the keep-one-line-statements option because I think that just leads to code that's more difficult for beginners to read and more prone to bugs. I'm not aware of that coding style being used in any official Arduino code. And one statement per line certainly doesn't violate the Arduino formatting style.

[wmarkow]

@per1234, thank you for your input about AStyle. I did some quick test on how Arduino IDE formats the code and I have found this a bit strange; take a look on one of my comments before. I have noticed like Arduino IDE doesn't force a specific brackets formatting. I had the feeling that this:

if (a == 5)
{
  a = 4;
}

is correctly formatted, and also this is correctly formatted:

} else if (a == 3) {
  a = 2;
}

Maybe it is just a matter of AStyle configuration file (just like you pointed)? I'm not so familiar with AStyle. It could be worth to check.

Because the issue I have noted above and because I'm also a Java programmer (and I'm using Eclipse), I started to use Eclipse formatter, because that was (for me) the fastest way to start experimenting with formatting. But enyway, I think I will take a look again at AStyle formatter.

I think the best would be to have:

• automated process of formatting (like executing some script that will format all of the sources)
• two different formatting styles: NASA formatter for RF24 library and Arduino formatter for the code of examples.

Going back to my exepriments with Eclipse formatter.
In my https://github.com/wmarkow/Arduino/commits/eclipse-formatter-poc branch I have just batch formatted the Arduino's examples with Eclipse formatter. The fromtter XML has been prepared by me by modifying the formatting rules in Eclipse and checking how it works on the Arduino's examples (I wanted to have as small changes as possible while formatting). You can take a look. Mostly it has reformatted the comments.
In my fork of RF24 library I have did the same in my https://github.com/wmarkow/RF24/commits/fix_for_%23391 branch. Examples are formatted with Arduino fromatter and other source code is formatted with NASA formatter. NASA fromatter rule for Eclipse have been prepared by me according to this NASA C++ guide.