code formatting guidelines

[TK]

While enhancing the String class (WString.cpp/.h), I have replaced each tab by 2 spaces, so that the visible indentation is the same for all users.
Some use spaces (like me), some use tabs, and we all use tab widths (or space equivalent) of 2, 4, or 8, or whatever. Meaning that the indentation has looked different for all of us due to a mix of tabs and spaces.

Is there a guideline what settings to use in the coding software so that code will look the same for all of us? I haven't found anything about that, I have searched for "code formatting" and "spaces tabs". That's why I am going to ask that here.
The only thing I found was
http://www.arduino.cc/en/Reference/StyleGuide  which is for personal use
and
http://www.arduino.cc/en/Reference/APIStyleGuide  which is for library development, but does not contain info about formatting.

We have certain rules at work for code formatting, so that when putting it under version control, the VCS doesn't have to save changes data due to different whitespace formatting.
Guidelines could be:
- no trailing whitespace (should be self-evident)
- 2 or 4 spaces indentation, no tabs. Alternative: only tabs, no spaces at all.
- 1 empty line at max, no 2 or more
Their existence does not target the convenience of VCS, but of the users checking the changes that were made and that are shown by the VCS. (some programs can hide whitespace changes, but that's the wrong approach in my opinion).

If the decision is made to set up some guidelines, they could be added to the APIStyleGuide.

[Victor Aprea]

I don't know of a style guide, but I could be wrong. Check out http://astyle.sourceforge.net/ though, it's a super useful for enforcing style as a post-process.

Kind Regards,

Vic

Victor Aprea // Wicked Device

victor...@wickeddevice.com

T: @vicatcu

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

[Paul Stoffregen]

When contributing to Arduino, or any well established open source project, please try to avoid unnecessarily changing white space.  Especially in code you're not actually editing for a functional reason, please leave it alone!

The net result of unnecessary white space changes is your pull requests are much harder to review, and if accepted, they have a much higher chance of breaking other pending pull requests or patches maintained by 3rd parties.  There are indeed many derivatives/forks of Arduino with varying amounts of customization.

If you're thinking of making things optimal, please try to focus on optimizing the amount of human time & attention needed to review your pull request.  The fewer lines altered, the better.  I know it's tempting and can see valuable to reformat ugly and inconsistent white space.  Cleaner & consistently formatted code seems so desirable.  But the thing that's in limited supply, which should be the goal of optimization, is the human developer hours to review and maintain the code base.  Reformatting white space is terribly wasteful of human developer time, especially when your edits cause other pending pull requests to no longer automatically merge!

[Victor Aprea]

Yep, another cool trick with github is to add ?w=1 to a URL ignore whitespace; see https://github.com/blog/967-github-secrets

Victor Aprea // Wicked Device

victor...@wickeddevice.com

T: @vicatcu

[Tom Igoe]

Well said Paul, thank you.

Tom Igoe
--
sent on the go. please forgive any terseness or typos

[TK]

The net result of unnecessary white space changes is your pull requests are much harder to review, and if accepted, they have a much higher chance of breaking other pending pull requests or patches maintained by 3rd parties.  There are indeed many derivatives/forks of Arduino with varying amounts of customization.

If you're thinking of making things optimal, please try to focus on optimizing the amount of human time & attention needed to review your pull request.  The fewer lines altered, the better.  I know it's tempting and can see valuable to reformat ugly and inconsistent white space.  Cleaner & consistently formatted code seems so desirable.  But the thing that's in limited supply, which should be the goal of optimization, is the human developer hours to review and maintain the code base.  Reformatting white space is terribly wasteful of human developer time, especially when your edits cause other pending pull requests to no longer automatically merge!

 
I see your point. Accepted. I will consider it next time!
It would especially be frustrating if automatic merge failed due to formatting changes. I did not know before this could be an issue.

But what about guidelines in general?
Should we have some which would be applied on code sections that are undergoing changes?

[Andrew Kroll]

Tabs traditionally have always been 8 spaces on a computer, nothing else.
Any other value comes from typewriters. We aren't writing love letters here.
So if you write something new, please use 8 spaces.

--

[TK]

Am Sonntag, 24. April 2016 16:37:17 UTC+2 schrieb Andrew Kroll:

Tabs traditionally have always been 8 spaces on a computer, nothing else.
Any other value comes from typewriters. We aren't writing love letters here.
So if you write something new, please use 8 spaces.

I disagree. The traditional tab width has been 8 spaces, that is true. But it's useless for code formatting. Imagine you have an indentation of 5 steps, this would be 40 spaces. The majority of your code line will be shifted off the screen. I think more than 4 is inefficient. I personally use 2, but this might be too few to see the indentation immediately. 4 would be a good tradeoff.

[Adrian Godwin]

Wouldn't it be wonderful if appropriate tabs were actually defined in the file, perhaps as a line like

!.!...!...!...!...!...!...!

[Andrew Kroll]

If your code indents are so deep that you have problems with it, it is time to rethink your code.

[per1234]

In a way Arduino already does have standard formatting guidelines, as used in the IDE's Auto Format. Now you may say that's just for sketches but as users get more experienced they will want to start looking at the source of the libraries and cores so it makes sense for the formatting to be consistent throughout. Auto Format uses Artistic Style, the configuration is at https://github.com/arduino/Arduino/blob/master/build/shared/lib/formatter.conf. For some reason https://github.com/arduino/Arduino/blob/master/format.every.sketch.sh uses a different configuration https://github.com/arduino/Arduino/blob/master/examples_formatter.conf which makes no sense. Of course, when you're editing preexisting code it's best practice to follow the current formatting style and any changes in formatting should be made in a separate pull request.

[Andrew Kroll]

Well...

1: Terminals always use 8 space tabs.

2. DOS and CP/M use 8 space tabs.

3. Unix uses 8 space tabs.

4. Linux uses 8 space tabs.

5. VT100 uses 8 space tabs.

6 ANSI uses 8 space tabs.

(do I REALLY need to go on here???)

Mac and Win environments set them to four, creating confusion when code was transferred back and forth.

Get a clue already...

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

--

Visit my github for awesome Arduino code @ https://github.com/xxxajk

[Paul Stoffregen]

On 04/24/2016 11:21 PM, Andrew Kroll wrote:

Well...

1: Terminals always use 8 space tabs.

2. DOS and CP/M use 8 space tabs.

3. Unix uses 8 space tabs.

4. Linux uses 8 space tabs.

5. VT100 uses 8 space tabs.

6 ANSI uses 8 space tabs.

(do I REALLY need to go on here???)

With the exception of Linux, is seems as if you're saying a variety of technologies that haven't been in widespread use since the end of the 1980s (*) are more relevant....

Mac and Win environments set them to four, creating confusion when code was transferred back and forth.

... than Macintosh and Windows, which have been by far the most widely used systems for the last 20+ years!

I personally use tabs, and I usually display them as 8 spaces because that's the default on Linux.  I use Linux.  But if there's any cause to show then as 4, like code with a mix of tabs and 4 spaces, I really don't see that as a big problem.  It's easy to change the setting.

When I contribute to Arduino, unless it's a whole new file, I use the same formatting as the surrounding code.  Most of the code is indented by 2 spaces, rather than tabs.  Really, that's not difficult.  Sometimes my finger instinctively hits the tab key, so I make a point before submitting a pull request to quickly review the lines I've edited and change any stray tabs to spaces (or spaces to tabs, the surrounding code uses tabs).  I only bother with cleanup at the end, when I prepare the pull request.  It seems like the polite thing to do, and it's really pretty easy.

Likewise, when I'm a guest in someone home and I help clean in their kitchen, I refrain from reorganizing their draws and cupboards.




(*) - Ok, BSD Unix, AIX, Solaris, HP/UX, IRIX & other commercial Unix systems were still widely used well into the 1990s, and some still retain a very tiny sliver of the installed base of computer systems today.  Some people still love BSD.  There really isn't any need to go on about old systems with very little practical usage today.

[Andrew Kroll]

On Mon, Apr 25, 2016 at 3:26 AM, Paul Stoffregen <pa...@pjrc.com> wrote:

On 04/24/2016 11:21 PM, Andrew Kroll wrote:

Well...

1: Terminals always use 8 space tabs.

2. DOS and CP/M use 8 space tabs.

3. Unix uses 8 space tabs.

4. Linux uses 8 space tabs.

5. VT100 uses 8 space tabs.

6 ANSI uses 8 space tabs.

(do I REALLY need to go on here???)

With the exception of Linux, is seems as if you're saying a variety of technologies that haven't been in widespread use since the end of the 1980s (*) are more relevant....

(*) - Ok, BSD Unix, AIX, Solaris, HP/UX, IRIX & other commercial Unix systems were still widely used well into the 1990s, and some still retain a very tiny sliver of the installed base of computer systems today.  Some people still love BSD.  There really isn't any need to go on about old systems with very little practical usage today.

That wasn't the point. The point is (despite your feelings, mine or anyone else, or who has market share) tabs have always been 8.

Eight space indents make code a whole lot easier to read, and, as I said before, if your indents are so deep that you can't follow it, nobody else will be able to either. You are better off refactoring your code because it is going to be a horrible thing to look at and try to figure out. The point is that us older people do have a ton of experience in this area. Yes, there has traditionally been a fight on tab sizes, but that really only started when some moron decided 2 spaces or 4 spaces was a good idea--- and now you know why it takes these companies so long to find errors -- it does matter.

All that aside, you could reformat things as you like, and tell git to ignore white-space changes. That is why we have the --ignore-space-change option :-) Which is also very useful for reviewing cleaned up indent code.

--

[Maya Posch]

So the take-away message here is that every project should just use tabs, and configure one's editor/IDE to display said tabs in the way they find most pleasing?

Or is there a disadvantage of this approach which I am not aware of?


Maya


On 25/04/2016 13:04, Andrew Kroll wrote:

> --
> You received this message because you are subscribed to the Google Groups "Developers" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc <mailto:developers+...@arduino.cc>.

[Andrew Kroll]

The problem with using actual 0x09 (tab) character is in printing it. Tab chars on your printer will come out as 9, and everything will be misaligned. The actual correct way to do this is to use spaces, so that everyone gets the same alignment.

To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

[Andrew Kroll]

**clarification... will print as 0x09, i.e. line up to the next 8 space area. Happens on my postscript laser printer, and every other real (i.e. non-win printer) printer..

Never embed actual tabs. There is lots of this in the arduino source, and it prints and displays horribly.

[Andrew Kroll]

Actually, windows text modes/shell/powershell still use 8 space tabs.

1: Save the attached file.

2: 'type PATH\TO\FILE\tabtest.txt

3: I get 8 spaces here on a laptop I just borrowed.

If mac is unix-like, you should be able to use cat instead of type.

There's your proof, and I needn't say any more. Facts tell the real story :-)

[TK]

@Andrew Kroll: All your comments are right, citing that tab is and has been 8 spaces in most programs. I also agree that we should use spaces instead of tabs, because spaces give a consistent output always.
But I disagree about the tab size we should use. I vote for 4 spaces.
Your comment

> That wasn't the point. The point is (despite your feelings, mine or anyone else, or who has market share) tabs have always been 8.

>Eight space indents make code a whole lot easier to read, and, as I said before, if your indents are so deep that you can't follow it, nobody else will be able to either. You are better off refactoring your code because it is going to be a horrible thing to look at and try to figure out.

isn't fully right. I have quite some situations where the code (just a few lines) is indented by 5 or 6 steps, and this is makes sense and is not confusing. It "could" get confusing if the indentation was too long...
Therefore 2 spaces are my favorite. Still I vote for 4 as the best compromise.