Refactoring restructures existing code to make its intent, design, and flow clearer while preserving its behavior. Treat a method as a readable story: expose meaningful steps, name them well, and keep related details at a consistent level of abstraction. section 2.5 section 3.2.5
Turn reminder delivery into named decisions
A reminder loop can be split into shouldSendReminder and sendEmail, separating eligibility, message delivery, and error handling. A later stream-based version further flattens the caller, but is worthwhile only when it remains clearer than a simple loop. section 3.2.3
Use refactoring to reduce cognitive load without mechanically pursuing smaller methods:
- Extract a cohesive operation when its name reveals business intent, removes complexity or repetition, or restores one abstraction level in the caller. section 2.5
- Reduce nesting with well-named methods, early returns, combined conditions, or declarative iteration when those changes simplify control flow. section 3.2.3
- Investigate unexplained complexity before changing it; weigh tests, dependencies, production timing, detectability, usage, and the consequences of regressions. section 3.2.5
A chunk is a meaningful unit of code that reads as a single recognizable step, such as a method call, a conditional block, a loop, an error-handling block, a pipeline, or a system-boundary interaction. A chunk is too small when it has no meaning on its own (a setup assignment, a single arithmetic operation). A chunk is too large when it combines several recognizable steps: - two unrelated decisions in the same block - validation and persistence together - multiple system-boundary interactions grouped - a branch body that contains more than one expression
A chunk is a recognizable step. Finding chunks helps decide where a long method needs clearer scene- and action-level structure. section 2.5
Metrics can identify taxing methods, but they do not replace judgment. A lower cognitive-complexity score is not automatically better: dense stream pipelines can obscure intent, and a straightforward loop may be the clearer design. section 3.2.3
