Skip to content

Commit 8fed14b

Browse files
iamdanfoxbulldozer-bot[bot]
iamdanfox
authored and
bulldozer-bot[bot]
committed
Minimal README with some examples (#43)
README now demonstrates the formatter output, and links to the recommended usages (gradle/intellij)
1 parent 5f079f5 commit 8fed14b

File tree

1 file changed

+84
-99
lines changed

1 file changed

+84
-99
lines changed

‎README.md

Lines changed: 84 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -4,43 +4,101 @@
44

55
# palantir-java-format
66

7-
`palantir-java-format` is a program that reformats Java source code to comply with
8-
[Palantir Java Style][].
7+
_A modern, lambda-friendly, 120 character Java formatter._
98

10-
It is a fork of [google-java-format], but intending to achieve the following goals:
9+
- [IntelliJ plugin](https://plugins.jetbrains.com/plugin/13180-palantir-java-format)
10+
- [Gradle plugin](https://github.com/palantir/gradle-baseline#compalantirbaseline-format)
1111

12-
* Enforce the Palantir Java Style, whose main difference compared to Google's style is that we use 120 character lines and 4 space indent.
12+
It is based on the excellent [google-java-format](https://github.com/google/google-java-format), and benefits from the work of all the [original authors](https://github.com/google/google-java-format/graphs/contributors). palantir-java-format is available under the same [Apache 2.0 License](./LICENSE).
1313

14-
* Produce more compact code - Keep long method chains and invocations, as well as assignments and lambdas, on a single line, if we can break only the last argument of a method call, or the last method call in a chain.
14+
## Upsides of automatic formatting
1515

16-
* don't break [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.
16+
- reduce 'nit' comments in code reviews, allowing engineers to focus on the important logic rather than bikeshedding about whitespace
17+
- bot-authored code changes can be auto-formatted to a highly readable style (we use [refaster](https://errorprone.info/docs/refaster) and [error-prone](https://errorprone.info/docs/patching) heavily)
18+
- increased consistency across all repos, so contributing to other projects feels familiar
19+
- reduce the number builds that trivially fail checkstyle
20+
- easier to onboard new devs
1721

18-
We thank everyone who's worked on google-java-format for their good work and for making it available for free online. It's thanks to their work that we could incorporate our coding style preferences into a formatter so easily.
22+
## Downsides of automatic formatting
1923

20-
[google-java-format]: https://github.com/google/google-java-format
21-
[Palantir Java Style]: https://github.com/palantir/gradle-baseline/blob/develop/docs/java-style-guide/readme.md
22-
[NON-NLS markers]: https://stackoverflow.com/a/40266605
24+
- if you don't like how the formatter laid out your code, you may need to introduce new functions/variables
25+
- the formatter is not as clever as humans are, so it can sometimes produce less readable code (we want to fix this where feasible)
2326

24-
## Using the formatter
27+
Many other languages have already adopted formatters enthusiastically, including typescript (prettier), go (gofmt), rust (rustfmt).
2528

26-
### from the command-line
29+
## Motivation & examples
2730

28-
[Download the formatter](https://github.com/palantir/palantir-java-format/releases)
29-
and run it with:
31+
(1) before:
3032

33+
```java
34+
private static void configureResolvedVersionsWithVersionMapping(Project project) {
35+
project.getPluginManager()
36+
.withPlugin(
37+
"maven-publish",
38+
plugin -> {
39+
project.getExtensions()
40+
.getByType(PublishingExtension.class)
41+
.getPublications()
42+
.withType(MavenPublication.class)
43+
.configureEach(
44+
publication ->
45+
publication.versionMapping(
46+
mapping -> {
47+
mapping.allVariants(
48+
VariantVersionMappingStrategy
49+
::fromResolutionResult);
50+
}));
51+
});
52+
}
3153
```
32-
java -jar /path/to/palantir-java-format-<version>-all-deps.jar <options> [files...]
54+
55+
(1) after:
56+
57+
```java
58+
private static void configureResolvedVersionsWithVersionMapping(Project project) {
59+
project.getPluginManager().withPlugin("maven-publish", plugin -> {
60+
project.getExtensions()
61+
.getByType(PublishingExtension.class)
62+
.getPublications()
63+
.withType(MavenPublication.class)
64+
.configureEach(publication -> publication.versionMapping(mapping -> {
65+
mapping.allVariants(VariantVersionMappingStrategy::fromResolutionResult);
66+
}));
67+
});
68+
}
3369
```
3470

35-
The formatter can act on whole files, on limited lines (`--lines`), on specific
36-
offsets (`--offset`), passing through to standard-out (default) or altered
37-
in-place (`--replace`).
71+
(2) before:
3872

39-
***Note:*** *There is no configurability as to the formatter's algorithm for
40-
formatting. This is a deliberate design decision to unify our code formatting on
41-
a single format.*
73+
```java
74+
private static GradleException notFound(
75+
String group, String name, Configuration configuration) {
76+
String actual =
77+
configuration.getIncoming().getResolutionResult().getAllComponents().stream()
78+
.map(ResolvedComponentResult::getModuleVersion)
79+
.map(
80+
mvi ->
81+
String.format(
82+
"\t- %s:%s:%s",
83+
mvi.getGroup(), mvi.getName(), mvi.getVersion()))
84+
.collect(Collectors.joining("\n"));
85+
// ...
86+
}
87+
```
88+
89+
(2) after:
90+
91+
```java
92+
private static GradleException notFound(String group, String name, Configuration configuration) {
93+
String actual = configuration.getIncoming().getResolutionResult().getAllComponents().stream()
94+
.map(ResolvedComponentResult::getModuleVersion)
95+
.map(mvi -> String.format("\t- %s:%s:%s", mvi.getGroup(), mvi.getName(), mvi.getVersion()))
96+
.collect(Collectors.joining("\n"));
97+
// ...
98+
}
99+
```
42100

43-
### IntelliJ, Android Studio, and other JetBrains IDEs
101+
## IntelliJ plugin
44102

45103
A
46104
[palantir-java-format IntelliJ plugin](https://plugins.jetbrains.com/plugin/13180)
@@ -61,84 +119,11 @@ When enabled, it will replace the normal `Reformat Code` action, which can be
61119
triggered from the `Code` menu or with the Ctrl-Alt-L (by default) keyboard
62120
shortcut.
63121

64-
The import ordering is not handled by this plugin, unfortunately. To fix the
65-
import order, download the
66-
[IntelliJ Java Google Style file](https://raw.githubusercontent.com/google/styleguide/gh-pages/intellij-java-google-style.xml)
67-
and import it into File→Settings→Editor→Code Style.
68-
69-
### Eclipse
70-
71-
A palantir-java-format Eclipse plugin is not currently published but can be built individually.
72-
Once built, drop it into the Eclipse
73-
[drop-ins folder](http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fp2_dropins_format.html)
74-
to activate the plugin.
75-
76-
The plugin adds a `palantir-java-format` formatter implementation that can be
77-
configured in `Window > Preferences > Java > Code Style > Formatter > Formatter
78-
Implementation`.
79-
80-
### Third-party integrations
81-
82-
* Gradle plugins
83-
* [Spotless](https://github.com/diffplug/spotless/tree/master/plugin-gradle#applying-to-java-source-google-java-format):
84-
* [sherter/google-java-format-gradle-plugin](https://github.com/sherter/google-java-format-gradle-plugin)
85-
* Apache Maven plugins
86-
* [coveo/fmt-maven-plugin](https://github.com/coveo/fmt-maven-plugin)
87-
* [talios/googleformatter-maven-plugin](https://github.com/talios/googleformatter-maven-plugin)
88-
* [Cosium/maven-git-code-format](https://github.com/Cosium/maven-git-code-format):
89-
A maven plugin that automatically deploys google-java-format as a
90-
pre-commit git hook.
91-
* [maltzj/google-style-precommit-hook](https://github.com/maltzj/google-style-precommit-hook):
92-
A pre-commit (pre-commit.com) hook that will automatically run GJF whenever
93-
you commit code to your repository
94-
95-
### as a library
96-
97-
The formatter can be used in software which generates java to output more
98-
legible java code. Just include the library in your maven/gradle/etc.
99-
configuration.
100-
101-
#### Maven
102-
103-
```xml
104-
<dependency>
105-
<groupId>com.palantir.javaformat</groupId>
106-
<artifactId>palantir-java-format</artifactId>
107-
</dependency>
108-
```
122+
## Future works
109123

110-
#### Gradle
124+
- [ ] 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.
111125

112-
```groovy
113-
dependencies {
114-
compile 'com.palantir.javaformat:palantir-java-format:<version>'
115-
}
116-
```
117-
118-
You can then use the formatter through the `formatSource` methods. E.g.
119-
120-
```java
121-
String formattedSource = new Formatter(JavaFormatterOptions.builder().style(Style.PALANTIR).build())
122-
.formatSource(sourceString);
123-
```
124-
125-
or
126-
127-
```java
128-
CharSource source = ...
129-
CharSink output = ...
130-
new Formatter(JavaFormatterOptions.builder().style(Style.PALANTIR).build())
131-
.formatSource(source, output);
132-
```
133-
134-
Your starting point should be the instance methods of
135-
`com.palantir.javaformat.java.Formatter`.
136-
137-
## Building from source
138-
139-
```
140-
./gradlew publishToMavenLocal
141-
```
126+
[NON-NLS markers]: https://stackoverflow.com/a/40266605
142127

143128
## License
144129

@@ -175,4 +160,4 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
175160
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
176161
License for the specific language governing permissions and limitations under
177162
the License.
178-
```
163+
```

0 commit comments

Comments
 (0)