java-conventions

Scope

• Language-level rules for Java 25 only — syntax, style, naming, visibility, structure, methods, streams, exceptions, comments.
• Architecture (BCE, layering, packaging) is not in this skill — see bce.
• Build, packaging, framework, and protocol rules are not in this skill — see java-cli-script, java-cli-app, microprofile-server, zb, etc.
• When a composed skill specifies a rule, the composed skill wins; this skill is the fallback baseline.

Java Version & Syntax

• target Java 25; assume all features are GA — never use --enable-preview
• use modern syntax naturally: var, records, sealed types, pattern matching, text blocks, switch expressions
• use var for local variable declarations where the type is obvious from the right-hand side
• use module imports (e.g. import module java.net.http;) over individual type imports
• do not import packages from java.base — it is automatically available
• use switch expressions with arrow syntax (case X -> ...) over old case X: statements with break
• use pattern matching for instanceof — if (o instanceof String s) over cast-and-assign
• use pattern matching in switch for type-based dispatch
• use the diamond operator <> for generic type inference
• never use raw generic types — always parameterize
• prefer void main() / void main(String... args) over public static void main(String[] args); instance main, not static

Java SE APIs

• use Java SE APIs over writing custom code — the standard library has it, usually in java.util, java.nio.file, java.net.http, or java.time
• prefer the most specific Java SE type for the domain — Path over String, URI over String, Duration over long millis, Instant/LocalDate over Date/long

Visibility & Modifiers

• avoid private methods (including private static helpers) — prefer package-private (default) so same-package unit tests can exercise them directly, including edge cases, without round-tripping through the public API
• avoid private fields — prefer package-private so same-package tests can read or seed state without reflection or extra accessors
• reserve private for genuinely sensitive state (credentials, security tokens, invariants that must never be observed externally); the burden of justification is on private, not on package-private
• do not use final on fields — exception: static final for constants like LOGGER
• do not use final on local variables or parameters
• do not use constructor injection — prefer field injection in CDI contexts
• avoid mutable static fields