Hello everyone,

I would like to get the discussion started around automatic code formatting
+ enforcing and how we get there.

Currently we use Checkstyle *check* to enforce formatting. However, the
problem with that is that you still have to manually do the actual
formatting.

What I would like to propose is the usage of *Spotless* (
https://github.com/diffplug/spotless) for *checking* and *enforcing* Java
code style (it can also enforce code style for Scala, Markdown, ... btw).
Spotless is being used by many projects (
https://github.com/search?l=gradle&q=spotless&type=Code) and comes
essentially with two tasks:
* *spotlessCheck*: Checks that sourcecode satisfies formatting steps
* *spotlessApply*: Applies code formatting steps to sourcecode in-place


*Code format*

The problem with code format is that there is no single format that can
satisfy the preferences of everybody. However, from my experience, once
people start to use *any* code format that produces consistent results
across *Eclipse**/IntelliJ/cmd line*, people stop worrying about code
format details.
This is also one of the reasons why the creators of Go decided to have a
code formatter built-in (https://go.dev/doc/effective_go#formatting):

*Formatting issues are the most contentious but the least consequential.
> People can adapt to different formatting styles but it's better if they
> don't have to, and less time is devoted to the topic if everyone adheres to
> the same style. The problem is how to approach this Utopia without a long
> prescriptive style guide.*
> *With Go we take an unusual approach and let the machine take care of most
> formatting issues. The gofmt program (also available as go fmt, which
> operates at the package level rather than source file level) reads a Go
> program and emits the source in a standard style of indentation and
> vertical alignment, retaining and if necessary reformatting comments.*



I would like to propose using the Google Java Format with Spotless. The
reason for this format is essentially that this is a widely-adopted code
format that is designed specifically for code reviews (since we're spending
more time reviewing code than writing it).
Additionally, it produces consistent formatting results across
*Eclipse**/IntelliJ/cmd
line*, which I think is another very important factor.

Thus, our initial Gradle spotless configuration could look similar to the
above below:











*pluginManager.withPlugin('com.diffplug.spotless') {    spotless {      //
don't run spotlessCheck during gradle check task during the transition
phase      enforceCheck = false      java {        target
'src/main/java/**/*.java', 'src/test/java/**/*.java',
'src/jmh/java/**/*.java'        googleJavaFormat()      }    }}*

We don't have to use Google Java Format. Spotless also supports formatting
the code with other formats, but from previous experience the Google Java
Format seemed to be really the only one to produce consistent results
across *Eclipse**/IntelliJ/cmd line*.


*How do we get to a point where the entire codebase is properly formatted
(and enforceCheck = false can be removed)?*

Now this is a difficult question. Obviously we don't want to have a single
*format-everything* commit, as that would affect lots of in-flight PRs.

There would have to be some form of gradual formatting, for example module
by module. Spotless offers something called Ratched (
https://github.com/diffplug/spotless/tree/main/plugin-gradle#ratchet) that
allows to enforce code format gradually (but I'm not sure this would be a
good thing either).

How exactly we'd like to approach this transitioning phase this is a
completely separate discussion, but I feel like at least we could get the
ball rolling so that we make it also easier for newcomers to contribute to
the project, since it would be straightforward for them to make their PRs
adhere to the code format and also save time during PR reviews.


Eduard

Reply via email to