# Java Code Smells > The detection catalogue for Java code smells: Long Method, God Object, Feature Envy, Primitive Obsession, Data Clumps, Shotgun Surgery, Divergent Change, Mysterious Name, Mutable and Global Data, Data Class, Loops, Lazy Element, Refused Bequest, boolean blindness, null-heavy APIs and leaky abstraction, plus how modern Java changes the list and the routing table from a finding to the refactoring that fixes it. Use when auditing code for structural problems, before planning a refactoring, when one change keeps fanning out across many files, when several refactorings could address one finding, when a switch over a sealed type carries a default branch, or when deciding whether a suspect pattern is actually a problem. Detection and severity only — refactoring mechanics are java-refactoring, navigation-chain depth is java-law-of-demeter, and the economics of duplication and premature abstraction are java-dry-kiss-yagni. - Skill: `robsonkades/java-code-smells` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add robsonkades/java-code-smells` - Raw SKILL.md: https://api.skillmd.com/api/skills/robsonkades/java-code-smells/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: robsonkades (https://skillmd.com/u/robsonkades) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robsonkades/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: ```text 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: | Priority | Typical evidence | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Critical/high | Security, money or data-integrity failure; repeated incidents; unsafe concurrent state; change is already blocked by the structure | | Medium | Recurring co-change/defects with a bounded refactoring seam and adequate characterization tests | | Low/monitor | Readability cost with little change pressure, speculative future benefit, or migration cost larger than demonstrated harm | | No action | Intentional boundary/representation, generated code, framework contract, or candidate falsified by ownership/change evidence | 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](references/catalogue-within.md) — 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](references/catalogue-between.md) — 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](references/smell-to-refactoring.md) — 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](references/modern-java.md) — 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](references/worked-pass.md) — 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](scripts/primitive-obsession/verify.sh) — 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.