java-engineer

Java — policy & pitfalls

Baseline knowledge of the Java language (records, sealed, pattern matching, text blocks, streams, var, generics, Optional API) is assumed — this skill does not teach the language. It encodes the project policy and the traps that keep appearing in code review.

Setup Check (run first)

Before writing non-trivial code, verify:

1. JDK version — java --version, and target version in pom.xml (<maven.compiler.release>) or build.gradle(.kts) (java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }). Adjust feature use if < 17. Current LTS: Java 25 (released Sept 2025); Java 21 is the previous LTS. Prefer LTS releases for new projects.
2. Build tool wrapper — use ./mvnw / ./gradlew, never a globally installed mvn / gradle.
3. Lombok — look for lombok in dependencies. If present, prefer @RequiredArgsConstructor / @Slf4j / @Builder; if absent, do not introduce Lombok unless asked.
4. Static analysis — error-prone, checkstyle, spotbugs, pmd. Respect existing rules; do not add new violations.
5. Preview features — if build uses --enable-preview, some features behave differently. Check flag before relying on preview syntax.

MUST DO

• Optional is a return type only. Never a parameter, field, or element of a collection.
• Value classes → record. DTOs, events, results, config snapshots. Not JPA entities (records are final and have no no-arg constructor).
• Closed hierarchies → sealed + exhaustive switch. Compiler catches new cases.
• switch expression over if / else if chains. Pattern-matching switch over instanceof chains.
• Fields final unless you have a reason to reassign.
• Fail fast at boundaries — Objects.requireNonNull in public-API constructors; validate invariants in record compact constructors.
• try-with-resources for anything AutoCloseable — including ExecutorService (Java 19+).
• Virtual threads for blocking I/O (Executors.newVirtualThreadPerTaskExecutor()). Not for CPU-bound work.
• Structured concurrency for multi-call fan-out: try (var scope = new StructuredTaskScope.ShutdownOnFailure()) { ... }.
• Parameterized logging: log.info("user_updated userId={} status={}", id, status).

MUST NOT DO

• No Optional.get() without prior isPresent() — use .map(...).orElseThrow(...) or .orElse(default).
• No raw types (List instead of List<Foo>), no @SuppressWarnings("rawtypes") to silence warnings.
• No returning null from a collection-returning method. Return List.of() / Collections.emptyList().
• No checked exceptions leaking into Stream / lambda. Wrap into an unchecked domain exception at the boundary.
• No catching Exception / Throwable to "make the compiler happy". Handle a specific type or propagate.
• No mutating input collections. Make a defensive copy: List.copyOf(input).
• No synchronized around a blocking call on a virtual thread — it pins the carrier thread. Use ReentrantLock.
• No Thread.sleep / blocking I/O on parallelStream() — shared common pool, starves other work.
• No mutation of Stream.toList() result — it's unmodifiable (JDK 16+).
• No PII / tokens / raw passwords in logs.

Reference Guide

Load when	File
Debugging subtle language / API behavior (Optional, Stream, switch, records, generics)	references/pitfalls.md
Records, sealed hierarchies, pattern-matching switch, preview features (pitfalls & traps, not syntax tutorials)	references/modern-java.md
Writing concurrent code (virtual threads, structured concurrency, ExecutorService lifecycle, ThreadLocal traps)	references/concurrency.md
File / stream / socket I/O, charsets, partial reads, NIO buffers	references/io.md

Output Format

When producing code:

1. A short plan (1–3 bullets) of what's changing.
2. The code.
3. A checklist of the non-obvious MUST rules applied.

When reviewing code: call out MUST-DO / MUST-NOT violations explicitly and suggest the minimal fix.