Formatting Java Source Code

[wfouche]

Use a Java source formatting tool so that code formatting is standarised.

Option 1: use Google Java Format. We have no control over how the code is formatted, the Google Standards are strictly enforced including comments which are reflowed across lines and using a 100 character line length.

Experimented with formatting the Jython source tree (src folder) using Windows Powershell command:

Get-ChildItem -Path src -Include *.java -File -Recurse | ForEach-Object { jbang run com.google.googlejavaformat:google-java-format:1.29.0 --aosp -r $_.FullName }

Option 2: Use the Eclipse Java Formatter. It does not reformat Java comments

jbang-fmt makes it easy to run the Eclipse Java Formatter.

jbang-catalog.json

{
  "aliases": {
    "jbang-fmt": {
      "script-ref": "jbang-fmt@jbangdev/jbang-fmt",
      "description": "A script that formats Jython's Java Source Code",
      "arguments": [
        "--line-length",
        "90",
        "--java",
        "8",
        "--indent-with",
        "space",
        "--indent-size",
        "4",
        "src"
      ]
    }
  }
}

Applied jbang jbang-fmt to the Jython source tree:

Processed 896 files (758 changed, 138 clean, 0 skipped) in 2,1s

[wfouche]

Option 2 is supported by PR #32

[jeff5]

Use the Eclipse Java Formatter. It does not reformat Java comments

You have to customise it to the Jython standard. On the wiki is a very old version of the config you can import -- or could in some ancient Eclipse. For Jython 2 I use very nearly that.

For Jython 3 and experiments in another repo, I have more sophisticated versions, one tuned specifically to make code fit in "book width" panels. (I hesitate to share as I keep tweaking. I find it a bit difficult to keep my adjustments in sync because of the way Eclipse treats formatting preferences in sub-projects.) Only these later ones do the clever formatting of comments adaptive to margin.

jbang-fmt makes it easy to run the Eclipse Java Formatter.

Surely you want to format in the IDE? I do that all the time.

[wfouche]

On the wiki is a very old version of the config you can import

OK, will use it as a starting point.

Surely you want to format in the IDE? I do that all the time.

Yes.

I create a new PR and close the current one.

[wfouche]

New PR #33 created.

@jeff, I have not applied the formatting updates to the Java source files yet. Run Maven from an IDE and see if the output is what you expect.

Task: spotless:apply

[jeff5]

Surely you want to format in the IDE? I do that all the time.

Yes.

I have not applied the formatting updates to the Java source files yet. Run Maven from an IDE and see if the output is what you expect.

I mean I frequently press ctrl-shift-F (Eclipse) or ctrl-K-F (VSCode). The IDE then applies the formatting with which I have configured it to the selection on screen.

I think the issue is that when we edit the two source files, we haven't formatted to a project convention, not that we lack a script that goes through the codebase applying one. It's easily solved by installing the convention in your favourite IDE and applying it.

There is a twist: the project convention about comments beginning with a space needs to allow for the //DEPS lines. I think the format from the Wiki may allow for that, or if it couldn't then, you can now in Eclipse.

Turns out VSCode reads the Eclipse formatting definitions, although it makes it practically impossible to compose or inspect one without Eclipse.

[wfouche]

@jeff5, the Java formatting settings that you use in Eclipse can easily be exported to a xml file. The build.gradle file in the PR supports the Eclipse Java Formatter (JDT) but it just lacks an up to date eclipse-java-formatter.xml file. The file exists in the PR, just need to be updated with your settings.

The formatter currently ignores JBang directives.

// spotless:off
//SOURCES JythonCli.java

//DEPS org.tomlj:tomlj:1.1.1
//DEPS org.junit.jupiter:junit-jupiter:5.13.3
//DEPS org.junit.platform:junit-platform-console:1.13.3
// spotless:on

[jeff5]

the Java formatting settings that you use in Eclipse can easily be exported to a xml file.

That's how it got on the wiki (and how it gets to VSCode). Ah! I see I didn't add a link when I mentioned the wiki. I'll download it, see how shabby it is, change it minimally, and then I think we just have to apply it to the two source files.

[jeff5]

It was quite shabby, in that I think the version was too old for VSCode to read it. Though, TBH I had a lot of trouble with VSCode.

Here is a version that has been through a recent Eclipse. I made these changes from the version on the Wiki:

1. The width of comments is 70.
2. The width of comments is measured from the start of text (so an indented comment is still 70 wide).
3. Comments that start on column 1 are not formatted (useful for preserving //DEPS and commented-out code).

However, VSCode does not respect the third of these settings, while Eclipse does.

Jython-2017-v2.xml

[jeff5]

The way to disable formatting is:

//@formatter:off
//SOURCES JythonCli.java

//DEPS org.tomlj:tomlj:1.1.1
//DEPS org.junit.jupiter:junit-jupiter:5.13.3
//DEPS org.junit.platform:junit-platform-console:1.13.3
//@formatter:on

Unfortunately, you can't apply that to the first line of a file and it still be the first line.

[wfouche]

@jeff5 , thanks for the Jython-2017-v2.xml file.

I've removed the first line from the two Java files. Not having this line in the Java files does not impact end-users at all.

The two Java files are now formatted according to the template you provided.

PR #33

[jeff5]

Not having this line in the Java files does not impact end-users at all.

I wondered about that, but assumed it was useful somewhere (maybe on Linux).

The two Java files are now formatted according to the template you provided.

Isn't that all we need to close the issue, i.e. not the 8 scripts?

Adding the formatter profile is worthwhile: I may do that for Jython as the wiki is not really a viable repository. But there seems no reason to have all this build apparatus, just for formatting, when we don't actually have to build the project (e.g. build a JAR). Formatting is something you do as you write, and might sometimes want to disregard for clarity.

[wfouche]

We could also use Gradle task spotlessCheck to validate that code changes are properly formatted during PR testing.

Although it might seem like a lot of additional (not critically required) stuff at the moment, I think it is beneficial (long term) to add the additional files.

[wfouche]

I may do that for Jython as the wiki is not really a viable repository.

That's a nice idea.

[jeff5]

Ok, I'll review it in this form and we can see how we get on with it in the baseline. Four of the new files are boilerplate anyway.

We could also use Gradle task spotlessCheck to validate that code changes are properly formatted during PR testing.

Yes, that's a reasonable bit of automation. I would want it to be a "warning" not a failure though. (That's probably the wrong term. There's a way of expressing this in the CI job.)

I'm worried slightly about the maintenance: I find Gradle valuable elsewhere, where things are complicated, but it is always telling me that what I spent many hours learning is deprecated and I have to learn something else.