refactoring

Refactoring: Smells & Techniques

A comprehensive guide to detecting code smells and applying refactoring techniques to improve design, clarity, and maintainability.

---

Read On Demand

Read When	File
Identifying code smells or reviewing a diff/PR for bloaters	Code Smell Catalog
Deciding which refactoring technique to use	Refactoring Techniques
Choosing the right pattern, scenario-based decisions, or review workflow	Decision Guide
Only when user asks where a pattern applies in a specific language	Language Idioms

---

Always-On Guardrails

• Never auto-remove TODO comments. TODOs require manual human decision — surface them, don't delete them.
• Tidy just in time. Tidy immediately before or after a known behavior change: before, the exact work is clear; after, the design friction is fresh. Avoid fixed technical-debt quotas, which invite speculative cleanup at the wrong time and place. If leadership reserves capacity, treat it as permission and slack, not a quota; fix the incentive that prevents timely tidying. Timebox standalone tidying only for deliberate practice, recovery from a conscious shortcut, or mapping an unfamiliar, unhealthy codebase.
• Rule of Three before extracting. Wait for the third duplication before Extract Method / Extract Class. Two points don't reliably reveal the right abstraction.
• No tests, no refactor. Don't refactor blind — add a safety net first.
• Extraction needs no new tests. Helpers extracted during refactoring stay covered by the existing public-API behavior tests; writing unit tests against them re-couples the suite to structure (see testing's mock-fragility guidance).
• Pair comment tidyings. When deleting redundant comments, also scan for missing why comments worth adding.

---

Smells → Techniques (Quick Reference)

Smell	Detection Signal	Technique(s)
Long Method	>10 lines, multiple responsibilities	Extract Method (Rule of Three)
Large Class	>10 methods, multiple concerns, hard to test	Extract Class (Rule of Three)
Primitive Obsession	String/int constants for domain concepts	Create Type/Object
Long Parameter List	>3-4 parameters, related params	Introduce Parameter Object
Data Clumps	Same variables in multiple places	Extract Class
Comments	Code needs a comment to be understood (see smells.md for subtypes)	Extract Method/Variable, Rename, Introduce Assertion, Write Tests
Uncommunicative Name	Name needs a comment, single letters, generic placeholders, missing units	Rename / Introduce Variable

For the full Techniques → When to Use table, see techniques.md.

---

Techniques by Goal

• Testability: Extract Method → Extract Class → Replace Conditional
• Reduce duplication: Extract Method → Replace Conditional → Introduce Variable
• Readability: Rename → Introduce Variable → Simplify Conditional → Extract Method
• Better design/coupling: Extract Class → Move Method/Field → Replace Conditional

---

When NOT to Refactor

Sometimes code size, complexity, or structure is justified:

• Complex algorithms that genuinely need many lines (with clear comments explaining why)
• Declarative structures like configuration objects or test data (accept longer parameter lists)
• Temporary code that will be replaced soon (refactoring cost > benefit)
• One-off utilities where extracting adds more boilerplate than it saves
• Unstable code that's still in flux — wait until requirements stabilize
• Performance-critical paths where refactoring would harm speed (profile first)
• Code without tests — refactor only with a safety net (see Always-On Guardrails)
• Only two occurrences of similar code — Rule of Three (see Always-On Guardrails); premature DRY tends to produce the wrong abstraction

Always ask: "Does this complexity serve the code's purpose, or does it obscure it?"

---

External References

• Refactoring Guru: Code Smells - Bloaters
• Martin Fowler: Refactoring Catalog — 72+ techniques organized by operation
• Principles: SRP, OCP, DRY
• Attribution: Tim Ottinger (comments); Fowler Refactoring; Martin Clean Code

---

Benchmark

Scenario: .benchmarks/scenarios/refactoring-001-long-method.md · Run: 2026-06-14

Model	Without	With	Delta
claude-opus-4-8	83%	100%	+17%
claude-sonnet-4-6	33%	100%	+67%
claude-haiku-4-5	0%	100%	+100%

PASS (strongest signal). Decisive on weak models (haiku 0→100%): enforces smell-naming, Extract-Method-first, in-place scope, rule-of-three. Keep as-is. Gate per .agents/skills/skill-optimizer/rules/release-gates.md.