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

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.

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.

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?"

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"