Java Code Smells

Java Code Smells

Purpose

A smell is evidence, not a verdict. This skill runs a detection pass whose output is a short, prioritised list of findings — each with the code it names, the evidence, a severity argument, and the java-refactoring technique that addresses it. The failure modes it prevents: reporting everything pattern-matching a smell (noise the team ignores), and rewriting code during what was supposed to be a diagnosis.

Workflow

Use Java 21 without preview as the example baseline. Inspect Maven/Gradle release settings, toolchains and CI/runtime versions before suggesting records, sealed types or pattern switches; do not upgrade the project or enable preview features as part of detection. The catalogue also applies to older Java, with recommendations conditional on its supported language level.

1. Scan for signals, not smells. Size outliers (methods, classes, parameter lists), change history (git log --follow on files that appear in every PR), duplication, and dependency fan-in/fan-out. Signals say where to look; the catalogue says what you found.
2. Classify against the catalogue — read references/catalogue-within.md for findings inside one class, references/catalogue-between.md for findings about coupling between classes. Check the smell's false positives before recording it.
3. Weigh severity from risk, not size. Combine change frequency and blast radius with business/security criticality, defect evidence, test/observability confidence, ownership, reversibility and migration cost. A rarely edited authorisation or money-movement path may outrank a frequently edited formatter. Repository history is evidence, not a veto.
4. Record findings, do not fix them. Each finding: smell name, location, evidence, severity argument, the named java-refactoring technique — routed through references/smell-to-refactoring.md, which also says what decides between competing techniques and when the honest recommendation is no refactoring. Fixing happens in a separate pass under that skill's safety workflow.

If history is shallow or unavailable, say which change-pressure claims cannot be established. Use source-level evidence for current coupling, but do not invent recurring co-change or defect history. Name what additional evidence would distinguish a finding from a monitor-only lead.

Rules

• No finding without evidence a reviewer can check: a metric, a diff that fanned out, a duplicated block's two locations. "This looks wrong" is not a finding.
• Stable code gets a lower change-pressure score, not immunity. Dormant compatibility, security, concurrency and data-integrity defects still warrant findings when their impact and evidence are strong; absence of tickets is weak evidence when failures are silent.
• One structural cause often shows as several smells (a God Object produces Feature Envy in its neighbours and Shotgun Surgery in its callers). Report the cause once, not each symptom separately.
• An exhaustive switch over a sealed type with no default is not the Switch Statements smell — it is one of its fixes. Read references/modern-java.md before flagging any switch, record, or Optional usage.
• A comment apologising for code ("hack", "careful here") is a search lead, not a finding. Preserve comments that encode an invariant, upstream defect, compatibility constraint or measured workaround; report the underlying structure only when independently evidenced.
• Never bundle a fix into the detection pass. Detection changes no code.

Severity and decision record

For each candidate, record this compact tuple:

location + structural signal
evidence and counter-evidence
change pressure + impact if wrong
test/observability confidence
plausible refactoring and migration surface
decision: finding | monitor | no action

Do not multiply ordinal scores and pretend the result is quantitative risk. Use the dimensions to expose the argument, then rank findings relative to this repository:

Before recommending a move, identify externally observed contracts: serialized fields, database mapping, reflection, dependency injection, native-image configuration and module exports. A smell inside such a boundary may be real while the safe recommendation is staged migration, not immediate cleanup.

References

• Catalogue: within a class — Long Method, Large Class, Primitive Obsession, Data Clumps, Temporary Field, Duplicate Code, Dead Code, comments-as-deodorant, boolean blindness, Speculative Generality, Mysterious Name, Long Parameter List, Mutable Data, Loops, Lazy Element.
• Catalogue: between classes — Feature Envy, Shotgun Surgery, Divergent Change, Message Chains, Middle Man, Refused Bequest, Inappropriate Intimacy, Switch Statements, null-heavy APIs, leaky abstraction, Global Data, Alternative Classes with Different Interfaces, Data Class.
• Smell → refactoring — the routing table from a recorded finding to the java-refactoring techniques that address it, what decides between competing techniques, the sequences that must run in order, and when the correct output is no refactoring at all. Read at step 4, when turning findings into recommendations.
• Modern Java: dissolved and created smells — what records, sealed types and Optional removed from the classic catalogue and what they added. Read before flagging switches, records, or Optional chains.
• A worked smell pass — one realistic service audited end to end: signals, findings, severity weighing, and the false positive that was deliberately not reported. Read when unsure how to weigh or phrase findings.
• Primitive confusion check — run with a POSIX shell and JDK 21+ when assessing whether distinct identifier types prevent a real argument swap. It compiles with --release 21, runs the before/after cases and checks the intentional compile failure. This demonstrates type safety, not application behavior or performance.