Skip to content

EAMxx Code Formatting Standards

To enforce consistent code format throughout EAMxx, we make use of an autoformatting workflow, carried out via Github Actions in the E3SM repository.

  • The tool we employ is clang-format, and the version we have chosen is v14.1
  • The standard we maintain is largely identical to the LLVM Coding Standards, and a list of the handful of customizations of this convention are enumerated in the configuration file $EAMXX_ROOT/.clang-format.
    • See this How-to Guide for additional details on how to configure clang-format on your chosen development machine.

Automated Workflow Summary

  • The eamxx-format workflow runs automatically and passes or fails based on adherence to our formatting standard.
  • The workflow is triggered by any Pull Request (PR) that modifies EAMxx code.
    • It is also triggered by other PR-related triggers, such as pushing changes, or converting from draft to ready.
  • All code modified by a PR must be formatted prior to merging.
  • It is not necessary for your code to be formatted upon opening a Pull Request, but feel free to clang-format as you develop if that is your preference.
    • The one situation for which opening a pre-formatted PR may not be preferred is if the file has never previously been clang-format-ed and requires a large number of changes. - I.e., touching the majority of lines in a file for format-only changes will make it difficult for a reviewer to determine which lines were changed for substantive reasons. - In this case, please refrain from formatting the code prior to opening the PR, and, instead, run clang-format once the PR is approved to be merged and make that the final commit.
  • As of now, the eamxx-format workflow only considers files that are edited by the Pull Request.
  • In addition to the pass/fail status, the workflow, provides the path to any files that caused the failure.
    • This information is found on the Summary page for any failed eamxx-format Job.2

  1. It turns out that this is important because there really are differences in behavior across versions. ↩

  2. To get to this summary, select the Checks tab at the top of the PR page and select the eamxx-format workflow from the left sidebar. The summary is in the main pane of the page with the title clang-format-linter summary.3 ↩

  3. Note that this can also be accessed the long way around by following the Actions link at the top of the E3SM repository page; select eamxx-format from the All workflows section of the Actions sidebar; then choose the most recent run that is associated with your PR, which should be near the top of the list. ↩