java-style

Java style & design preferences

Scope

How to write and shape Java code in this repository: formatting, language-feature use, complexity and reuse tradeoffs, and exception handling. Static-analysis tooling has its own page; see References.

Formatting and language

• Let Spotless handle formatting and import cleanup. Use spotless:apply before verifying when formatting changed.
• Use imports instead of inline fully qualified type names. Write Arrays.stream(...), not java.util.Arrays.stream(...). PMD enforces this with the narrow UnnecessaryFullyQualifiedName rule.
• Prefer the Java file APIs' specified UTF-8 defaults for Files.readString, Files.readAllLines, and Files.writeString. Keep an explicit charset for APIs that otherwise use the platform default and for protocol conversions whose byte encoding is part of the contract.
• Use Java 25 LTS language/runtime features where they make the code clearer, but do not be clever for its own sake.
• Keep code ASCII unless an existing file or domain requirement clearly needs Unicode.
• Give Java Unicode escapes used as character data a domain name before use, including escapes in literals, regular expressions, fixtures, and similar data. Bind \\uXXXX syntax to a constant whose name identifies the character or intentional character group, and use that constant at call sites and in test scenario tables. Search for the same code point before adding a constant so coupled validation and rendering rules share one definition instead of accumulating parallel escapes. This rule does not apply to escapes shown only in identifiers or explanatory comments.
• Avoid unrelated metadata churn and broad rewrites.

Reuse and dependency selection

• Before writing or retaining hand-made utility logic, search the Java 25 API and the APIs of dependencies declared directly in pom.xml. Start with the operation's owning type rather than a generic helper: for example, check Process and Thread for Duration overloads, String for bounded searches, Files.walkFileTree for recursive file lifecycle work, sequenced collections for first/last or reversed views, and the compiler tree API before scanning Java syntax. In tests, also check the exact AssertJ API before maintaining custom assertion loops. Prefer these APIs when they state the same contract directly and remove conversion, restoration, parser, or accumulator machinery.
• Resolve the version actually used by Maven and consult that version's official API documentation or Javadocs before adopting an overload or dependency method whose behavior is subtle. Verify null rejection, empty-input behavior, encounter order, defensive-copy and mutability guarantees, end-exclusive bounds, timeout precision, interruption, exception cleanup, symlink traversal, and short-circuiting as applicable. Add a focused regression at that boundary. A similarly named API is not a replacement when it changes one of those properties; retain explicit local code and record the concrete mismatch instead.
• Prefer a well-maintained dependency over hand-written infrastructure when it materially reduces code or complexity and the resulting API remains readable. Do not reject a library merely because it adds a dependency; compare the whole implementation, operational, security, and maintenance cost against keeping the custom code.
• A new library candidate must have an upstream release within the previous 12 months, an unarchived repository, no deprecation or unmaintained notice, an open-source license compatible with this project, and at least 100 GitHub stars. Verify each condition from current primary sources when making the recommendation rather than relying on remembered metadata.
• Also evaluate Java compatibility, security history, API stability, transitive dependency size, platform coverage, and native/runtime requirements. A candidate that meets the minimum activity, license, and popularity bar may still be rejected when it increases operational complexity or does not replace enough custom behavior; record that concrete trade-off in the issue or review.
• Before adding a dependency, inspect existing declared dependencies and the Java standard library for the same capability. Do not couple source code to an undeclared transitive dependency. Treat a new runtime or build dependency as an architecture decision when its lifecycle or platform impact is non-trivial, and update the owning ADR or add one when required by the ADR policy.
• Guava is a directly declared dependency. Before writing or retaining small character-boundary loops, delimiter-only regex splitting, null-to-empty String adapters, immutable collection collectors, or manually capped FIFO queues, check the matching Guava API (CharMatcher, Splitter, Strings, immutable collectors, or EvictingQueue) against the exact resolved Guava version. Use it when it removes custom mechanism and makes the intended semantics more obvious. Preserve the original contract explicitly: Splitter keeps empty fields unless configured not to; CharMatcher operates on UTF-16 characters and must not replace a code-point or domain-specific Unicode parser; Strings.nullToEmpty is for immediate String normalization, not for erasing a meaningful nullable state; and immutable or bounded collections must preserve order, duplicate, null, and mutation behavior. Prefer the JDK or focused custom code when the Guava form is longer, less domain-specific, or semantically different; do not perform broad mechanical collection churn.