Aligning text in the code.

[wwieder]

Are we aligning text in the CTSM code?

Maybe this discussion should be clarified, as @samsrabin had different interpretations. Notably:

• Sam thought we decided that was more trouble than it's worth; see "Lower priority" section of [notes from 2023-09-07](https://docs.google.com/document/d/1Qn9c7NiGxYMN3p47Fpa0QINLwwxzRpGXG61GsuGjVM0/edit#heading=h.3vr45vczwma.
• I thought when @ekluzek raised the question it was WRT going through and correcting existing code that's not being modified (except for the vertical alignment). Avoiding this seems OK to prevent scope creep on our work.
• Introducing new text that's not aligned (especially in code blocks that are otherwise tidy and easy to read) seems misguided.

Maybe a solution moving forward is to keep the code looking nice (when possible), but don't bend over backwards doing this. I appreciate that larger PRs and external contributions may make this simple 'rule' open for interpretation?

[ekluzek]

Ok the issue I created for this is #2144. That's especially for the part when we have a tool to change the code. It's not going to be worth it to do this change by hand.

I envisioned that new work coming in just wouldn't do vertical alignment. Since we've decided to break the vertical alignment that makes sense to me. But I could also be OK with putting minimal effort into this if you can easily keep the vertical alignment for new code you add. But I would also say just adding new code without vertical alignment and add white space to distinguish it, or place it such that it doesn't need it.

So maybe we need more discussion on thi

[billsacks]

I definitely see good arguments on both sides here. For now I'll just say that, if people do want to keep things aligned, there is a variety of editor support for this.

For emacs, there is a built-in align-regexp (I have this bound to C-x \). The usage is: select the lines you want to align, then run align-regexp and give it a regular expression to align on (e.g., for a simple case, give it '=' to align all of the equal signs in those lines). I have built a number of custom functions on top of this to do the common alignments we do in CTSM:

;; Define a function to align all commas on a line
;; adapted from http://www.emacswiki.org/emacs/AlignCommands
(defun f90-align-args (start end)
  "Align all commas on a line"
  (interactive "r")
  (align-regexp start end
                "\\(\\s-*\\)," 1 0 t))

;; Define a function to align the pieces of a Fortran argument list:
;; align on comma, then '::', then '!'
;; For some reason, this doesn't seem to work consistently (e.g., sometimes fails to work completely on the last line)
(defun f90-align-arg-hdr (start end)
  "Align the pieces of a Fortran argument list"
  (interactive "r")
  (align-regexp start end
                "\\(\\s-*\\),")
  (align-regexp start end
                "\\(\\s-*\\)::")
  (align-regexp start end
                "\\(\\s-*\\)!"))

;; Define a function to align the pieces of a Fortran variable declaration section:
;; align on '::', then '!'
(defun f90-align-var-decl (start end)
  "Align the pieces of a fortran variable declaration section"
  (interactive "r")
  (align-regexp start end
                "\\(\\s-*\\)::")
  (align-regexp start end
                "\\(\\s-*\\)!"))

;; Define a function to align assertions
(defun f90-align-asserts (start end)
  "Align equal signs and errMsg portions of assertions"
  (interactive "r")
  (align-regexp start end
                "\\(\\s-*\\)==")
  (align-regexp start end
                "\\(\\s-*\\)errMsg"))

;; Define a function to align items in an associate clause
;; (For best results, put a temporary comma before the '&' on the last line, which you can delete after running this function
(defun f90-align-associate (start end)
  "Align pointer and comma in associate clause"
  (interactive "r")
  (align-regexp start end
                "\\(\\s-*\\)=>")
  (align-regexp start end
                "\\(\\s-*\\),"))

A quick search for VSCode turns up https://marketplace.visualstudio.com/items?itemName=janjoerke.align-by-regex .

[ekluzek]

That does give a workflow to make sure things continue to be vertically aligned and make it easy to do. However, one of the reasons to NOT do vertical alignment is so that we don't create issues with git merge. So if we continue the practice of vertical alignment we are more likely to continue to have those issues.

The VSCode you give above is the first one listed among many, so it looks like this is easy to do in VSCode. And the demo of the one you give above looks easy to use as well.

So we could take the tack that we are going to keep doing vertical alignment, but make sure everyone has a tool to do it for them. And then when we have a formatting tool that we like, we run it, which will format everything consistently....

What are everyone's thoughts here?

[billsacks]

To add a little more of my own thoughts: My main thought is that if the main CTSM developers don't have a tool or easy way in their editor to do the alignment, then we should stop trying to do the alignment. If there's an easy way to do it in the editor, then I'd probably still come down slightly on the side of not trying to keep things aligned, but could imagine sticking with it, e.g., if enough CTSM scientists find significant value in it - as long as they understand that this does come with extra costs for the SEs. (Given the right editor tooling, like what I have in emacs, the costs are small when writing new code, but are larger for maintaining code, e.g., renaming variables becomes a pain and I often don't try to maintain alignment when doing that kind of thing.) I'm not sure I'd go so far as to put out guidance to not align code, though I can also see the argument that partially-aligned code is uglier than not-aligned-at-all code.

I am pretty skeptical that we'll be able to find a formatter that can automatically do the kind of alignment we currently do, because my experience is that automated things (like my emacs functions) can work in most cases but fall down in some unusual cases and need to be fixed by hand... and (key point!) that's even given that you manually select the lines of interest... I think it would be very, very hard to have rules that run the right alignment commands for each block of code without any manual intervention.