Palantir Refines Java Formatting: Lambda-Friendly, 120-Char Style
It is based on the excellent google-java-format, and benefits from the work of all the original authors. palantir-java-format is available under the same Apache 2.0 License.
Upsides of automatic formatting
- reduce 'nit' comments in code reviews, allowing engineers to focus on the important logic rather than bikeshedding about whitespace
- bot-authored code changes can be auto-formatted to a highly readable style (we use refaster and error-prone heavily)
- increased consistency across all repos, so contributing to other projects feels familiar
- reduce the number builds that trivially fail checkstyle
- easier to onboard new devs
Downsides of automatic formatting
- if you don't like how the formatter laid out your code, you may need to introduce new functions/variables
- the formatter is not as clever as humans are, so it can sometimes produce less readable code (we want to fix this where feasible)
Many other languages have already adopted formatters enthusiastically, including typescript (prettier), go (gofmt), rust (rustfmt).
Motivation & examples
(1) google-java-format output:
private static void configureResolvedVersionsWithVersionMapping(Project project) {
project.getPluginManager()
.withPlugin(
"maven-publish",
plugin -> {
project.getExtensions()
.getByType(PublishingExtension.class)
.getPublications()
.withType(MavenPublication.class)
.configureEach(
publication ->
publication.versionMapping(
mapping -> {
mapping.allVariants(
VariantVersionMappingStrategy
::fromResolutionResult);
}));
});
}
(1) palantir-java-format output:
private static void configureResolvedVersionsWithVersionMapping(Project project) {
project.getPluginManager().withPlugin("maven-publish", plugin -> {
project.getExtensions()
.getByType(PublishingExtension.class)
.getPublications()
.withType(MavenPublication.class)
.configureEach(publication -> publication.versionMapping(mapping -> {
mapping.allVariants(VariantVersionMappingStrategy::fromResolutionResult);
}));
});
}
(2) google-java-format output:
private static GradleException notFound(
String group, String name, Configuration configuration) {
String actual =
configuration.getIncoming().getResolutionResult().getAllComponents().stream()
.map(ResolvedComponentResult::getModuleVersion)
.map(
mvi ->
String.format(
"\t- %s:%s:%s",
mvi.getGroup(), mvi.getName(), mvi.getVersion()))
.collect(Collectors.joining("\n"));
// ...
}
(2) palantir-java-format output:
private static GradleException notFound(String group, String name, Configuration configuration) {
String actual = configuration.getIncoming().getResolutionResult().getAllComponents().stream()
.map(ResolvedComponentResult::getModuleVersion)
.map(mvi -> String.format("\t- %s:%s:%s", mvi.getGroup(), mvi.getName(), mvi.getVersion()))
.collect(Collectors.joining("\n"));
// ...
}
Optimised for code review
Even though PJF sometimes inlines code more than other formatters, reducing what we see as unnecessary breaks that don't help code comprehension, there are also cases where it will split code into more lines too, in order to improve clarity and code reviewability.
One such case is long method chains. Whereas other formatters are content to completely one-line a long method call chain if it fits, it doesn't usually produce a very readable result:
var foo = SomeType.builder().thing1(thing1).thing2(thing2).thing3(thing3).build();
To avoid this edge case, we employ a limit of 80 chars for chained method calls, such that the last method call dot must come before that column, or else the chain is not inlined.
var foo = SomeType.builder()
.thing1(thing1)
.thing2(thing2)
.thing3(thing3)
.build();
Palantir Java format Gradle plugin
You should apply this plugin to all projects where you want your java code formatted, e.g.
buildscript {
dependencies {
classpath 'com.palantir.javaformat:gradle-palantir-java-format:<version>'
}
}
allprojects {
apply plugin: 'com.palantir.java-format'
}
Applying this automatically configures IntelliJ, whether you run ./gradlew idea or import the project directly from IntelliJ, to use the correct version of the formatter when formatting java code.
./gradlew format can be enabled by using the com.palantir.baseline-format Gradle plugin.
Spotless
- See integration in Spotless Gradle plugin.
- See integration in Spotless Maven plugin.
IntelliJ plugin
A palantir-java-format IntelliJ plugin is available from the plugin repository. To install it, go to your IDE's settings and select the Plugins category. Click the Marketplace tab, search for the palantir-java-format plugin, and click the Install button.
The plugin will be disabled by default on new projects, but as mentioned above, if using the com.palantir.java-format gradle plugin, it will be recommended in IntelliJ, and automatically configured.
To manually enable it in the current project, go to File→Settings...→palantir-java-format Settings (or IntelliJ IDEA→Preferences...→Other Settings→palantir-java-format Settings on macOS) and check the Enable palantir-java-format checkbox.
To enable it by default in new projects, use File→Other Settings→Default Settings....
When enabled, it will replace the normal Reformat Code action, which can be triggered from the Code menu or with the Ctrl-Alt-L (by default) keyboard shortcut.
Future works
- preserve NON-NLS markers - these are comments that are used when implementing NLS internationalisation, and need to stay on the same line with the strings they come after.
Download Details:
Author: palantir
Official Github: https://github.com/palantir/palantir-java-format
License: Apache-2.0 license
