A code smell is a pattern in code that suggests something may be wrong underneath. Kent Beck and Martin Fowler popularised the term, and their framing carried a deliberate hedge: a smell is *suggestive*, not conclusive. It tells you where to look, not what to do.
The ones worth recognising
- Long function — several responsibilities in one place. Length is the symptom; multiple reasons to change is the disease.
- Large class — the same problem at a different scale, often a class that accreted rather than was designed.
- Long parameter list — usually a missing type. Five loose parameters are frequently one concept nobody named.
- Duplicated code — the honest kind is fine; the dangerous kind is two copies that must change together and will not.
- Feature envy — a method more interested in another object's data than its own. The behaviour is in the wrong place.
- Shotgun surgery — one conceptual change requires edits in eight files. The boundary is wrong.
- Primitive obsession — money as a float, an email as a string, an ID as an int. Types that could have prevented a class of bugs.
Why they are heuristics, not rules
Every smell has legitimate counter-examples. Duplication is often correct when the two copies serve different domains and will diverge. A long function is sometimes the clearest expression of a genuinely linear process, and splitting it into eight named steps can obscure rather than clarify.
The question that turns a smell into a decision
What change would this make hard? If the answer is a change you expect, fix it. If it is a change nobody will ever make, leave it. This converts a stylistic argument into a concrete prediction, and it is the question that separates useful refactoring from tidying.
Smells in generated code
Machine-written code produces a different distribution of smells. It rarely leaves the messy-looking ones — naming is consistent, formatting is clean, functions are reasonably sized. What it does produce is duplication across files, defensive handling for conditions that cannot occur, and several independently reasonable approaches to the same problem in one codebase. These are harder to spot precisely because nothing looks wrong locally.
Where they belong in review
Smells are conversation starters, and automated tools should surface them as such rather than as failures. "This function has grown to 200 lines" is a useful comment. "Build failed: function exceeds 50 lines" produces an arbitrary split at line 49 and no improvement in the design.
Frequently Asked Questions
Are code smells the same as anti-patterns?
No. An anti-pattern is a solution that is reliably wrong. A smell is an observation that something might be wrong — it needs judgement applied before it means anything.
Should linters enforce smells?
Report them, do not fail builds on them. Deterministic rules like formatting are fine to enforce; heuristics that need context are not.
Which smell matters most?
Shotgun surgery, in most codebases. It is direct evidence that module boundaries do not match how the system actually changes, and that is expensive in a way the others usually are not.
References
- Refactoring: Improving the Design of Existing Code — Code Smells — Martin Fowler
- The Agentic Engineering Trends Report 2026 — SaaSRise
About Jishu Labs
Jishu Labs is a software development company founded in 2016. We build custom software, AI/ML systems, and full-stack web and mobile applications for clients, and we make eight AI tools for software teams.