Use ClangFormat as code formatter for examples #58
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
A script included in the repository formats the code in the examples according to Arduino's standard style. Since the formatter tool does not have a recursive capability, `find` must be used. This results in a fairly long and complex command. Adding line breaks to split the command into its individual arguments, with indentation to indicate the structure of these arguments makes the command easier to understand.
The repository includes a script that formats the example sketch code. This uses a `find` command to recurse through the example folders and run the formatter on each file with a relevant extension. Previously a regular expression was used for that matching. Although perfectly functional, the same can be achieved in an easier to understand and maintain manner using globs.
The `.ipp` and `.tpp` file extensions, commonly used for inline or template function definitions included in C++ header files, have now been added to the Arduino sketch specification as supported extensions. Even though it is unlikely such extensions will ever be used in the example sketches of this repository, it is best to be comprehensive in the extensions covered by the formatter script
The repository includes a script that formats the code in the examples. When running this script locally, the contributor must have the formatter tool installed and in the system PATH. Previously this dependency was only explained by a comment in the script, which is not likely to be seen by the contributor in advance of running it. This means they would encounter a somewhat cryptic error message. A more contributor friendly approach is for the script to check for the availability of the tool, then exit with a friendly error message if it is not found.
The repository includes a script that formats the code in the example sketches. Previously, this script was only provided to make it easy for contributors to achieve compliant code formatting while preparing a pull request. In addition to this effort to facilitate compliance, enforcement is implemented by a GitHub Actions workflow. Since the formatter tool does not have the directory tree recursion capability needed to process all the files in the repository, it is necessary to implement such capability using a `find` command. Previously this was done both in the script and the workflow. `find` is ridiculously complex and unintuitive, prone to confusing bugs. For this reason, it will be best to avoid maintaining redundant code for recursing through the example code files. This is accomplished by simply running the script from the workflow. Even though the two have different goals (making formatting compliant vs checking whether formatting is compliant), the two are easily aligned by formatting the files in the workflow, then checking for a diff. This approach has been widely used in other Arduino Tooling Team formatting check workflows and I find the diff is very effective at communicating which changes are required, likely more so than the approach previously used in the workflow.
For the sake of efficiency, the repository's GitHub Actions workflows are configured to only run when relevant files are modified. The formatter configuration file is one such file, yet was previously omitted from the paths filter.
The code formatting tool used by the Arduino IDE 1.x "Auto Format" feature is "Artistic Style". This was changed to ClangFormat in Arduino IDE 2.x. Now that the stable Arduino IDE 2.0.0 release has been made, this is now the official code formatting tool for use with Arduino sketches. Due to differences in the two tools, some unavoidable minor changes occurred in the formatting style. This meant that the Arduino IDE 2.x user may experience some unexpected changes to the unmodified official example sketches when running an "Auto Format". So the examples in this repository must be formatted to comply with the updated Arduino code style. The changes are mostly the result of ClangFormat being more "opinionated" than "Artistic Style" was under the fairly light-handed formatter configuration used by Arduino IDE 1.x Auto Format. Due to this factor, formatting changes required to bring the examples into compliance with the new style mostly do not conflict with the Arduino IDE 1.x style. The only exception is the more complex code of the ArduinoISP sketch. In this case, the sketch is more of a utility program than an example, so the formatting changes will not be impactful for users who continue to use the outdated Arduino IDE version.
per1234
added
type: enhancement
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The code formatting tool used by the Arduino IDE 1.x "Auto Format" feature is Artistic Style. This was changed to ClangFormat in Arduino IDE 2.x. Now that the stable Arduino IDE 2.0.0 release has been made, this is now the official code formatting tool for use with Arduino sketches.
Due to differences in the two tools, some unavoidable minor changes occurred in the formatting style. This meant that the Arduino IDE 2.x user may experience some unexpected changes to the unmodified official example sketches when running an "Auto Format". So the examples in this repository must be formatted to comply with the updated Arduino code style.
The changes are mostly the result of ClangFormat being more "opinionated" than "Artistic Style" was under the fairly light-handed formatter configuration used by Arduino IDE 1.x Auto Format. Due to this factor, formatting changes required to bring the examples into compliance with the new style mostly do not conflict with the Arduino IDE 1.x style. The only exception is the more complex code of the ArduinoISP sketch. In this case, the sketch is more of a utility program than an example, so the formatting changes will not be impactful for users who continue to use the outdated Arduino IDE version.