Accepted5 Nov 2026
0030. Write Java in Spring Framework's style, with clean-code rules the build enforces
Context and Problem Statement#
The Java code is meant to be a reference for engineers. Stages 0 and 1 formatted it with palantir-java-format (ADR-0006 and ADR-0021), but nothing checked how it was written beyond formatting and nullness. Reviewing it, the owner found it not clean enough:
- test names in two styles (snake_case sentences in the model, camelCase in the API tests);
- methods of 50 lines and more, and classes of nearly 700;
- JSON written as escaped strings in annotations;
- one-letter names, inline fully qualified names, comments that read as notes;
- enum constants run together on one line.
Most of the code to come is a Spring Boot application. How should Java code be written here, and how is it kept that way, by people and by AI assistants?
Decision Drivers#
- Code a Java and Spring engineer recognises and would hold up as an example.
- Rules the build checks, not habits: every finding fails the build.
- The same rules for people and AI assistants.
Considered Options#
- Format: Google Java Style (google-java-format), palantir-java-format (as before), or Spring Framework's style (spring-javaformat)
- Test names: camelCase with
@DisplayName,should..., snake_case sentences, ormethod_state_result - Enforcement: a written convention only, Checkstyle, or Checkstyle and PMD
Decision Outcome#
Chosen options: "Spring Framework's style", "method_state_result" and "Checkstyle", because
Spring's style is what the application's engineers read in Spring's own code, and Spring ships a
formatter and a Checkstyle module for it that keep it without effort.
- Format: spring-javaformat's Gradle plugin (
./gradlew format, andcheckFormatincheck) replaces Spotless with palantir-java-format. - Checkstyle runs on every source set with Spring's checks (
SpringChecks: import order,this.for fields, Javadoc form, lambdas, ternaries,*Testsclasses, ...) and ArchSim's clean-code rules: sizes and complexity, names, Javadoc on the public API, no JSON in strings, one enum constant per line, and test names.maxWarningsis 0, and a finding is never suppressed in the code. - An exception to a rule needs the owner's approval. It is a change to
config/checkstyle/, with its reason in a comment beside it. The owner approved two in ba9810d:LineLengthignores the last line of an annotated record component, which the formatter can't wrap;ClassFanOutComplexitydoesn't count the codec's annotations (@Default,@Ge,@Ui, ...), which declare a record's JSON rather than couple it to other code. - Spring's checks are taken with two changes. The
@authortag on every type isn't required: git records authors. Spring's nesting limits (three levels ofif,forandtry) are replaced with stricter ones: two levels ofif, one offor, one oftry. - Test sources (
src/test,src/apiTest,src/testFixtures) are exempt from the Javadoc checks,MagicNumberand the no-JSON-in-strings rule (suppressions.xml): their names document them, and their inputs may be JSON text and literal numbers. - Unnamed variables.
_is allowed as a pattern variable (PatternVariableName), asLambdaParameterNamealready allows it.catch (X _)still fails Spring's catch check, which refuses one-letter names. - Tests are named
method_state_result. Checkstyle tells test methods from others by their JUnit or jqwik annotation, and checks each against its own pattern. - The rules are written down in
docs/java-conventions.md, and the repository's skills (.claude/skills/:java-conventions,test-first,conventional-commits), pointed to byAGENTS.md, give them to AI assistants.
Consequences#
- Good, because the style is one a Spring engineer already knows, and
./gradlew formatkeeps it. - Good, because the build, not review, catches long methods, vague names and missing Javadoc.
- Bad, because adopting it reformatted every Java file (tabs), and the existing code had to be refactored to pass: about 2,700 findings, mostly mechanical.
- Bad, because spring-javaformat has no options: enum constants stay on separate lines only when each has its own Javadoc, so the convention requires one.
- Bad, because Spring's checkstyle module is built against an older Checkstyle API; a Checkstyle upgrade must be checked with it before it is taken.
Confirmation#
./gradlew build runs checkFormat and Checkstyle on every source set; the CI job java runs it.
Pros and Cons of the Options#
Google Java Style#
- Good, because it is the most widely documented guide and formatter.
- Bad, because it is not what the application's Spring engineers read daily.
palantir-java-format (as before)#
- Good, because nothing would need reformatting.
- Bad, because it formats only; the problems above are not formatting.
Checkstyle and PMD#
- Good, because PMD adds design rules (unused code, complexity, coupling).
- Bad, because much of it overlaps Checkstyle and Error Prone, and it is noisier.
More Information#
- Supersedes the formatting part of ADR-0006 and ADR-0021; the rest of both stands.
- spring-javaformat: https://github.com/spring-io/spring-javaformat
- Checkstyle: https://checkstyle.org/
- Robert C. Martin, Clean Code (2008)