Auto format configuration doesn't match classic Arduino IDE

[ubidefeo]

Describe the bug
The auto format configuration used by the Java IDE represents a de facto Arduino code style that has been established and consistent for years.
The configuration is defined here:
https://github.com/arduino/Arduino/blob/1.8.13/build/shared/lib/formatter.conf
The documentation is here:
http://astyle.sourceforge.net/astyle.html
I personally find it disturbing when running an auto format on a sketch based on an official sketch or documentation snippet results in formatting changes to the existing code and I'm sure this could cause confusion for beginners. My experience indicates that changing the formatting of the official sketches and documentation snippets may be extremely difficult politically.
So I think it's very important to have continuity in the formatting configuration between the two IDE. If we do make changes to the official code style, the change should be based on a conscious decision, rather than just an arbitrary change.
This is the sort of thing that becomes more problematic to change as time goes on.

Desktop (please complete the following information):
OS: Windows 10
Version: 2.0.0-beta.2-snapshot.f9730ab
Date: 2021-02-18T13:01:31.751Z
CLI Version: 0.16.0 alpha [c977a238]

Additional context
https://github.com/arduino/arduino-pro-ide/issues/339
arduino/Arduino#3941

[ originally reported by @per1234 ]

[tigoe]

+1 this. It's the feature I use most when teaching. Until it's available I can't use the 2.0 IDE in class.

[ubidefeo]

@tigoe
there's a patch in the works.
should be in the next beta which is not far from completion :)

[tigoe]

Update, still does not appear to work in beta 6.

[ubidefeo]

hi @tigoe

we're back on this issue, which board have you selected?
we know that because it requires some pre-compilation it can be slower on mbed based boards,
but it is working if you have a board selected

[tigoe]

Weird, why does autoformat depend on the board type? I've been using the nano 33iot, the mkr 1010, the Uno, and the nano 33ble with the new ide. Autoformat not working on any of them.

…

On Fri, Jun 11, 2021, 10:54 AM Ubi de Feo ***@***.***> wrote: hi @tigoe <https://github.com/tigoe> we're back on this issue, which board have you selected? we know that because it requires some pre-compilation it can be slower on mbed based boards, but it is working if you have a board selected — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#42 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAC45HZIBSHUGCJSNRS6CADTSIPTFANCNFSM4YG2CXPA> .

[tigoe]

Update, using 2.0.0-beta.11:

Auto format still not working.

test:

• make new sketch
• write blink code, without tabbing any lines
• press cmd-T
• Nothing happens

[tigoe]

Update, using 2.0.0-beta.12:

Auto format still not working.

test:

• cmd-N
• write blink code, without tabbing any lines
• press cmd-T
• Nothing happens

re: other issues which mention this, auto-format should follow the standards set by the Java IDE, IMO, for things like braces, etc.

[per1234]

Nothing happens

There is a bug that causes the auto format functionality to not work at all. That is being tracked here: #396

---

auto-format should follow the standards set by the Java IDE, IMO, for things like braces, etc.

I appreciate your care for this subject @tigoe. As the original author of this issue, I very much agree.

I'll provide an update about where we are on this:

At the time this issue was written, the Arduino IDE 2.x formatter was using the default ClangFormat configuration, since the team had not yet found time to work on a custom configuration. I was fortunate to be given the opportunity to improve on that situation. My efforts resulted in the auto format configuration you will see in the latest versions of the Arduino IDE 2.x on the occasions when the auto formatter actually runs and is not otherwise misbehaving (e.g., #543).

I dedicated myself to making every possible effort to finding a formatter configuration that would exactly reproduce the classic Arduino IDE's Auto Format. Unfortunately, I discovered that the differences between the Artistic Style code formatter tool used by the classic Arduino IDE and the ClangFormat tool used by Arduino IDE 2.x make it impossible to achieve a perfect match.

I produced a ClangFormat configuration that I believe gets as close as possible. Where there were unavoidable differences, I based the configuration exclusively on the results of comprehensive surveys of code style in official Arduino firmware projects which I performed in the pursuit of a previous unrelated project. The resulting configuration is stored here.

If anyone would like to propose improvements on that configuration, the time would be now, since it has not yet gone into widespread usage. However, any proposals must be based solely on the goal of reproducing the code style established by the classic Arduino IDE, rather than on arbitrary individual code style preferences.

Even though it is unfortunate that the switch resulted in some minor formatter style changes, ClangFormat is a well maintained industry standard tool that many advanced users will already be using in other contexts. Artistic Style is an excellent tool that has served the Arduino community well, but the developer has stated they are no longer able to maintain it as actively.

Even though the ideal is a consistent code style across the Arduino ecosystem, there will always be some who are not satisfied with whatever formatter configuration we provide, and that's fine. For this reason, it is important to allow the advanced users to configure the formatter according to their preferences.

Work is already underway to provide a global custom configuration capability similar to the formatter.conf system used by the classic Arduino IDE (#566).

There is also a nice advancement already in place: sketch-specific formatter configuration files. If a .clang-format configuration file is placed in the root of the sketch folder, the formatter will use that configuration for the sketch. Distributing this local configuration along with the a collaborative project ensures all contributions will be consistent with that code style.

---

The final essential part of the work will be to document the formatter configuration customization capabilities provided by the IDE.

[per1234]

I'm happy to say that support for the global custom formatter configuration file is now here: #1019

So the remaining task to close this issue is to document the system. Perhaps @arduino/ft_content can help us out with that?

You might find the description I wrote here to be a useful reference:

#94 (comment)

CC: @sebromero

[per1234]

We have now resolved this issue to the extent that is possible.

This consisted of the following:

• Reduce differences by using a custom ClangFormat configuration in the Arduino IDE:
  arduino/arduino-language-server@4083356
• Allow user configuration to reduce friction from unavoidable changes:
  #1009, #566: Use clang-format as the default sketch formatter. #1019
• Document user configuration system:
  • [MKC-496]Benjamindannegard/ide 2.0 auto formatter tutorial docs-content#317
  • https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-customize-auto-formatter
• Validation system to ensure unintentional changes are not introduced by ClangFormat updates:
  • Host standardized ClangFormat configuration file tooling-project-assets#250
• Use new ClangFormat configuration options to further reduce differences:
  • Update ClangFormat configuration file for ClangFormat 14.0.0 tooling-project-assets#254
  • Sync sketch formatter configuration from source #1285

We encourage those who have published Arduino code to run an "Auto Format" on it at the next release in order to bring it into compliance with Arduino's now slightly more comprehensive standardized code style. Due to the efforts to achieve consistency in this style, any changes that result are likely to also be compliant with the more permissive Arduino IDE 1.x "Auto Format".

For those using another editor for development, or with automated formatting checks, Arduino's official ClangFormat configuration file is hosted here:

https://raw.githubusercontent.com/arduino/tooling-project-assets/main/other/clang-format-configuration/.clang-format