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 in your codebase | Code Smell Catalog |
| Deciding which refactoring technique to use | Refactoring Techniques |
| Mapping a code smell directly to a pattern (quick activation lookup) | Pattern Triggers |
| Choosing the right pattern for a specific scenario | Decision Guide |
| Reviewing a diff/PR for bloater smells | Detection Checklist |
| Step-by-step code review and refactoring workflow | Code Review Workflow |
| Only when user asks where a pattern applies in a specific language | Language Patterns |
| Only when user asks for a multi-file before/after walkthrough | Real-World Examples |
Always-On Guardrails
- Never auto-remove TODO comments. TODOs require manual human decision — surface them, don't delete them.
- 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.
- 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 (What) | Complex expression needs comment | Extract Variable |
| Comments (What) | Code block needs comment | Extract Method |
| Comments (What) | Method purpose unclear from name | Rename Method |
| Comments (Precond) | Comment documents a required precondition | Introduce Assertion |
| Comments (Behavior) | Comment documents expected behavior/edge cases | Write Tests |
For the full Techniques → When to Use table, see techniques.md.
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?"
References
- Refactoring Guru: Code Smells - Bloaters
- Martin Fowler: Refactoring Catalog — 72+ techniques organized by operation
- Principles: Single Responsibility Principle (SRP), Open/Closed Principle (OCP), DRY (Don't Repeat Yourself)
- Attribution: Tim Ottinger on comments; Martin Fowler's "Refactoring: Improving the Design of Existing Code"