For discussion: initial configuration of Codee Fortran formatter with examples (`src/*.F90`) #707

climbfuji · 2025-12-08T18:26:06Z

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

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 · 2025-12-08T18:27:10Z

.codee-format

+ColumnLimit:     120
+CommentDirectivePrefixes: []
+DisabledDirectivePrefixes: []
+IndentSize:      2


To be discussed

NEPTUNE and UFS use 2 spaces for indentation. The CCPP framework code in src uses 3 at the moment. This particular change is responsible for most of the differences in this PR.

We currently have issues with lines that are too long so while this will not help a huge amount but it's at least in the correct direction.

climbfuji · 2025-12-08T18:27:37Z

.codee-format

+  FirstLineFit:    FitIfPossible
+BreakBeforeBinaryOperators: true
+Casing:
+  Identifiers:     Lowercase # Preserve


NEPTUNE uses Lowercase, "Preserve" is the codee default

Six of one, half of the other in the UFS.
My OCD is suggesting that we should adopt a convention and apply across UFS, but "Preserve" is fine for now

I'm fine with whatever so perhaps lowercase is best to appease the NEPTUNE?

lowercase is nice, but whatever works for SIMA and the UFS will do. Within NEPTUNE, we had to make an exception for a nuopc subdirecty, because esmf/nuopc uses CamelCase extensively, and the notorious long names in esmf code become unreadable unless you add underscores. Long story short, no strong preference here.

Is this just for the Fortran bits of the framework? If so, we can just make sure it is readable in lowercase.

Yes, only Fortran.

climbfuji · 2025-12-08T18:28:05Z

.codee-format

+FixedFormLabelAlignment: Right
+ContinuationIndentSize: DoubleIndentSize
+DoubleColonSeparator: AddAlways
+EndOfLineNormalization: Unix # Autodetect


Unix is NEPTUNE, Autodetect is Codee default

I looked at the documentation and don't fully understand this one?
(Maybe you or someone could explain (slowly) to me at out meeting tomorrow?)

I need to look this up, but as far as we all are concerned, Unix should be the correct choice.

I don't actually know if I've ever seen a case that mixes line endings in one file (as described in the codee documentation). If you use "auto-detect", it will use the first line ending across the entire file. We should definitely use "Unix" here so that all line endings, including Windows line endings for entire files/parts of files are converted to Unix.

Unix please!

climbfuji · 2025-12-08T18:28:32Z

.codee-format

+  LeftParenthesisKeyword: OnlyLeading
+  RightParenthesisExpression: NoLeading
+  RightParenthesisGeneric: NoLeading
+  RightParenthesisKeyword: OnlyTrailing # NoLeading


OnlyTrailing is NEPTUNE, NoLeading is Codee default

As expected, UFS is all over the place wrt "SpacesAroundOperators".
(I'm super impressed that NEPTUNE is following a standard!)

I do love the idea of adopting this (more granular?) level of code formatting.

No strong feeling but squeezing spaces makes lines shorter.

climbfuji · 2025-12-08T18:29:18Z

run_codee_tmp.sh

+    "src/ccpp_types.F90:free"
+)
+
+for entry  in "${files[@]}"; do


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.

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

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.

climbfuji · 2025-12-08T20:25:44Z

.codee-format

+# requested 2025/12/08 using the Codee Online Form
+IndentExceptions:
+  ModuleContains:  IndentBeforeAndAfter
+  Comments:        IndentIfAlreadyIndented # Indent


NEPTUNE is "Indent", here I am using "IndentIfAlreadyIndented"

Also note the comment above for ModuleContains exceptions and the missing support for TypeContains/FunctionContains etc exceptions.

Why? I'd prefer "Indent" over "IndentIfAlreadyIndented".
vs.

It's because of the CCPP metadata hooks in the Fortran code that are typically not indented. I think capgen's parser is fine if they get indented, though.

I'm for consistency so I prefer 'Indent'.

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 · 2025-12-10T17:45:36Z

.codee-format

+  FirstLineFit:    FitIfPossible
+BreakBeforeBinaryOperators: true
+Casing:
+  Identifiers:     Lowercase # Preserve


Six of one, half of the other in the UFS.
My OCD is suggesting that we should adopt a convention and apply across UFS, but "Preserve" is fine for now

dustinswales · 2025-12-10T17:52:54Z

.codee-format

+# requested 2025/12/08 using the Codee Online Form
+IndentExceptions:
+  ModuleContains:  IndentBeforeAndAfter
+  Comments:        IndentIfAlreadyIndented # Indent


Why? I'd prefer "Indent" over "IndentIfAlreadyIndented".
vs.

dustinswales · 2025-12-10T17:57:24Z

.codee-format

+FixedFormLabelAlignment: Right
+ContinuationIndentSize: DoubleIndentSize
+DoubleColonSeparator: AddAlways
+EndOfLineNormalization: Unix # Autodetect


I looked at the documentation and don't fully understand this one?
(Maybe you or someone could explain (slowly) to me at out meeting tomorrow?)

dustinswales · 2025-12-10T18:07:55Z

.codee-format

+  LeftParenthesisKeyword: OnlyLeading
+  RightParenthesisExpression: NoLeading
+  RightParenthesisGeneric: NoLeading
+  RightParenthesisKeyword: OnlyTrailing # NoLeading


As expected, UFS is all over the place wrt "SpacesAroundOperators".
(I'm super impressed that NEPTUNE is following a standard!)

I do love the idea of adopting this (more granular?) level of code formatting.

dustinswales · 2025-12-10T18:11:58Z

run_codee_tmp.sh

+#!/usr/bin/env bash
+
+files=(
+    "src/ccpp_constituent_prop_mod.F90:free"


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

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 · 2025-12-10T18:14:52Z

run_codee_tmp.sh

+    "src/ccpp_types.F90:free"
+)
+
+for entry  in "${files[@]}"; do


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

peverwhee · 2025-12-15T18:43:27Z

.codee-format

+  FirstLineFit:    FitIfPossible
+BreakBeforeBinaryOperators: true
+Casing:
+  Identifiers:     Lowercase # Preserve


I'm fine with whatever so perhaps lowercase is best to appease the NEPTUNE?

peverwhee · 2025-12-15T19:02:05Z

.codee-format

+  Comma:           OnlyTrailing
+  Concat:          Both
+  DoubleColon:     Both


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

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.

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

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?

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 added 2 commits December 8, 2025 10:32

Add initial .codee-format and temporary run_codee_tmp.sh

b016c99

Codee format src/*.F90

65d5c06

climbfuji commented Dec 8, 2025

View reviewed changes

climbfuji self-assigned this Dec 8, 2025

climbfuji marked this pull request as ready for review December 8, 2025 20:23

climbfuji requested review from dustinswales, gold2718, grantfirl, mkavulich and peverwhee as code owners December 8, 2025 20:23

Update format

43778b8

climbfuji commented Dec 8, 2025

View reviewed changes

dustinswales reviewed Dec 10, 2025

View reviewed changes

peverwhee reviewed Dec 15, 2025

View reviewed changes

For discussion: initial configuration of Codee Fortran formatter with examples (src/*.F90) #707

Are you sure you want to change the base?

For discussion: initial configuration of Codee Fortran formatter with examples (src/*.F90) #707

Uh oh!

Conversation

climbfuji commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

climbfuji Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

climbfuji Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

climbfuji Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dustinswales left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

For discussion: initial configuration of Codee Fortran formatter with examples (`src/*.F90`) #707

For discussion: initial configuration of Codee Fortran formatter with examples (`src/*.F90`) #707

climbfuji commented Dec 8, 2025 •

edited

Loading

climbfuji Dec 8, 2025 •

edited

Loading

climbfuji Dec 15, 2025 •

edited

Loading

climbfuji Dec 8, 2025 •

edited

Loading