Java Clean Code

Java Clean Code

Purpose

Make Java code that the next reader understands without running it. Two failure modes, not one: the method that does five things, and the class exploded into a dozen three-line fragments that communicate through fields and can only be understood by reading all of them. Both are unreadable; only the first is commonly named. This skill decides where to split, where to merge, and when to leave code alone.

Readability yields to correctness always, and to performance only with evidence. Keep the reproducible benchmark/profile and environment in the performance record; leave a short code comment only when a future maintainer could reasonably "simplify" a still-measured hot path.

Workflow

Before changing structure, inspect the compiler release/toolchain, framework lifecycle, affected callers and existing tests. No single authoring baseline is declared; references use Java SE 25 documentation. Clock needs Java 8+, List.copyOf Java 10+, records Java 16+, and RandomGenerator Java 17+. Use the project's supported alternatives; this skill does not authorize upgrades, preview features or new dependencies. When caller contracts or tests are missing, identify the gap and characterize observable results, effects and failure order before claiming a behaviour-preserving change.

1. State what the unit does in one sentence. Every "and", "then" or "unless" in that sentence is either a split point or evidence that the unit is coherent and only its name is wrong (naming is java-api-design's).
2. Check each method for abstraction level: does it mix policy ("apply the fee rule") with mechanics (rounding, string assembly, iteration bookkeeping)? Extract the mechanics under a domain name; keep the policy visible.
3. Check for hidden structure: ambient reads (now(), locale, static config) inside logic, fields used as scratch space between calls, methods valid only in a fixed order. Make dependencies parameters and make order impossible to get wrong.
4. Only then weigh size — count the concepts a reader must hold at once, not lines. A 30-line method at one abstraction level beats ten 3-line hops.
5. Re-run the tests. A change that alters behaviour is not a readability change; the safety workflow and mechanics for larger moves live in java-refactoring.

Split, keep or merge

Rules

• Prefer one abstraction level per method when named extractions reduce concepts held at once. Guards, resource scopes and trivial mechanics need not become helpers; consult the structure reference when extraction would only add navigation.
• Every extraction has a price — a name to trust and a hop to follow. Do not keep a fragment that has one caller, needs fields or three-plus parameters to share state with that caller, and cannot be understood without reading it. Inline it back.
• Section comments are a diagnostic, not a verdict. Stable domain steps often deserve named extractions; a dense algorithm, state machine or intentionally co-located hot loop may be clearer with phase/invariant comments. A comment that merely paraphrases syntax is noise; one that preserves rationale, invariant, units, protocol or measured constraint is design evidence.
• A method whose public contract promises an observational read must not expose a semantic write. Internal memoisation may be acceptable when it preserves results, thread safety, resource bounds and failure behavior; lazy I/O or externally visible mutation is not a harmless getter implementation. (Command–query separation in full is java-tell-dont-ask's.)
• For accidental internal call order, if b() is only valid after a(), merge them, pass what b needs as the return of a, or encode the order in a type. Preserve framework/protocol lifecycles and published APIs; documented state checks may be appropriate there. A new phase type is not automatically safer or clearer.
• No ambient reads in domain logic: LocalDate.now(), Locale.getDefault(), static configuration lookups belong at the boundary, passed in as Clock, Locale, values. Hidden inputs make behaviour untestable and irreproducible.

Production checks

• Concurrency: extraction that promotes locals to fields can make a previously reentrant operation race. Run concurrent calls when a refactor changes state lifetime; final on the field does not make the referenced accumulator safe.
• Failure atomicity: moving an effect into a helper does not make a workflow transactional. List effects and retry boundaries before rearranging persistence, messages or remote calls.
• Observability: preserve event names, correlation and error classification. Do not retain logs merely to narrate newly fragmented control flow.
• Compatibility: reflection, dependency injection, serialization and framework proxies may observe constructors, visibility and annotations that ordinary callers do not. An internal readability edit can still be a runtime contract change.
• Reviewability: separate semantic movement from renaming/formatting when practical. A smaller conceptual diff makes behavior preservation easier to establish than a lower line count does.

References

Deliver the concrete readability problem, why a split/merge (or no change) follows from the code, and the checks executed for behaviour preservation. Report untested assumptions; passing tests alone neither proves equivalence nor measures reader comprehension.

• Worked examples — an under-factored settlement method split by abstraction level, and an over-fragmented batch processor merged back, each with trade-offs and verification. Read before splitting or merging anything larger than a single method.
• Structure and coupling — detection heuristics, false positives and when-not-to-apply for abstraction levels, temporal coupling and hidden dependencies. Read when a rule above matches but the fix is not obvious, or the match might be a false positive.