Java Development (plain Java)

Everyday guidance for Java projects that are not tied to a framework. If the project uses Spring Boot, Quarkus, Helidon or similar, prefer that framework's skills for framework concerns and use this one for the plain-Java parts.

Rules that always apply

1. Detect before you write. Read pom.xml/build.gradle*, .mvn/, gradle/, .java-version/.sdkmanrc, .editorconfig, CI files, and a few source files. Match the build tool, Java release, formatter, naming, logging and test libraries already in use.
2. Never upgrade implicitly. Do not change the Java release, build-tool version, plugin or dependency versions, or add a formatter/linter/static analyzer the project lacks, as a side effect of another task. Suggest it and ask. Version upgrades are their own task (java-upgrade, if installed).
3. Use the wrapper (./mvnw, ./gradlew) when present; otherwise the installed mvn/gradle. Do not commit a wrapper unprompted.
4. Verify with a build. After any change run the project's own verification (./mvnw -B verify or ./gradlew build) and report the result. Run a narrower command first while iterating. If you could not run it, say so.
5. Ask the user before: changing public APIs or serialized/DB/wire formats, raising the Java release, adding runtime dependencies, adding tools to the build, deleting or weakening tests, changing CI, or when two reasonable designs have different trade-offs.
6. Prefer the standard library and small, explicit code over new dependencies. No Lombok unless already used.

Pick idioms by the project's Java release

Check maven.compiler.release/<release>, java.toolchain, or sourceCompatibility; never use a feature newer than that release. Summary (details and snippets in references/modern-java.md):