Initial configuration of Codee Fortran formatter with examples (src/*.F90)

[climbfuji]

Initial configuration of Codee Fortran formatter with examples (src/*.F90).

This PR adds an initial .codee-format configuration file for the free Codee Fortran formatter and a temporary script run_codee_tmp.sh to get started with the tool (note that the day-to-day usage will be much simpler than in the script). The PR also demonstrates the effect of the formatting rules for the four Fortran source files in src/.

The goal of this PR is to provide the necessary information to decide on the formatting rules we want to use. Once we have agreed on the format, we can update the src/*.F90 files as needed and merge this PR. The integration with GitHub actions and the simplified usage on the command line will come after that. In a 3rd PR, we will work on a tighter integration of the codee format config with the capgen Fortran write to make sure that the auto-generated code also complies with the formatting rules.

The majority of the diffs are because NEPTUNE (and UFS) use two whitespaces as indentation, whereas the files in src/ currently use 3 whitespaces. We can change the codee config, but every space we save makes the lines shorter. To see the remaining differences, please select "Hide whitespaces" when looking at the files changed.

User interface changes?: No

Working toward #703

Testing: No changes to the tests - GitHub actions CI tests passed
test removed:
unit tests:
system tests:
manual testing:

[climbfuji]

This is overly complicated and not really needed for ccpp-framework. Just for initial testing/demonstration purposes. This file will be either before this PR is merged, or at the latest once codee is integrated in GitHub actions.

[dustinswales]

Is the idea that we will pass any file modified in the current PR through the formatter as part of the PR?

[climbfuji]

My suggestion is to format all existing Fortran files in the repository as part of the PR. In a next step, implement GitHub actions. In a third step, integrate with capgen and make sure that the auto-generated code also complies with the formatting rules.

[dustinswales]

@climbfuji Thanks for incorporating the code formatter here!
I love the idea, we just need to decide on a few details and incorporate this into our workflows.
As a github action, running the formatter could be invoked either diagnostically (report format violations) or prognostically (fix format violations).

[dustinswales]

@climbfuji Is the "free" suffix here to use "free formatted" version of Codee?

[climbfuji]

No, I had some logic in that script previously that would use this, it's no longer there because not needed.

Since the script won't be merged, I didn't bother taking this out.

[dustinswales]

Is the idea that we will pass any file modified in the current PR through the formatter as part of the PR?

[peverwhee]

Can we remove the enforcement of Comma and DoubleColon white spacing?

We do this kind of thing (lining up intents, function arguments, etc) in SIMA quite often (which we prefer for ease of readability):

subroutine whatever(argument1, arg2, a3)
  integer,         intent(in) :: argument1
  real(kind_phys), intent(in) :: arg2
  integer,        intent(out) :: a3

[climbfuji]

There is a very good reason to not line up intents. If the longest line changes, then every single line has to change, even though there are no code changes. This increases the possibility of merge conflicts and make changes/pull requests unnecessarily longer. This is the reason why the code default is single whitespace, and why we've adopted it in NEPTUNE.

[peverwhee]

@dustinswales @gold2718 do you have a preference on this?

[gold2718]

While I am sympathetic to the argument that the one-space rule minimizes potential merge conflicts and PR simplicity (one of the goals of these tools), at the end of the day, the code exists for its human users and they need to be able to read it to understand it. I know at NCAR, the users (scientists and RSEs) strongly preferred lining up the colons to make it easy to pick out the variables. Who is the customer here?

[climbfuji]

We talked about this today in the meeting; we agreed that aligning the colons doesn't need to be done for the auto-generated code, it's enough to do this for the few handwritten Fortran files in the repository. Thus, we just "preserve" the whitespaces on a per-file basis.

And importantly, host models can do whatever they want for the rest of their code ...

[climbfuji]

Changed this to Preserve as per our discussion

[climbfuji]

I need to "unresolve" this conversation about whitespaces before/after colons. The argument was that these lines in CAM/SIMA are aligned for better readability. But this aligning doesn't just affect the white spaces before/after colons, but also before and after commas, parentheses, etc. See screenshot

Unless I change many of these SpacesAroundOperators to Preserve - which then defeats the purpose of using a formatter -, I'll get "unaligned" lines.

Going back to the previous comments and questions, "who is the audience"? The audience for the source code in ccpp-framework is ccpp-framework developers, not cam/sima scientists. I think it is ok to expect ccpp-framework developers to deal with non-aligned variable definitions in a handful of source files (and in auto-generated files, but these were never in question).

And, again, CAM/SIMA can do whatever it wants in their source code, independent on how we format ccpp-framework Fortran files.