Refactoring
Why it matters
Code grows messy as it grows. Quick fixes pile up, and near-duplicate logic spreads across files. This is especially common when an AI coding agent writes most of the code, because it will happily add a new copy of a pattern rather than reuse the old one. Each new feature then takes longer and carries more risk, because a change has to be repeated in several places and one of them gets missed. Refactoring pays that debt down before it slows everything else.
How to apply it
- Prove behaviour first. A set of tests, or at least a repeatable manual check, should pass before and after the change.
- Work in small steps and run the check after each one, so a mistake is easy to find.
- Do not mix a refactor with a feature. Keep it as its own change so a reviewer can see that nothing should have moved.
- Refactor where the next piece of work is going to happen, not everywhere at once.
- Stop when the code is clear enough. Endless polishing is also waste.
What it is
Refactoring is tidying code without changing what it does. A user should notice no difference. Typical moves are pulling copied logic into one shared place, renaming something confusingly named, or splitting a very long file into smaller pieces. The key rule is that behaviour stays identical. A change that alters behaviour is a rewrite, a bug fix or a new feature, and should be labelled as one.
Common mistakes
- Refactoring code that has no tests, so nobody can tell whether behaviour changed.
- Starting a large clean-up with no clear end and leaving half the code in the old style.
- Letting an AI agent restructure freely and accepting the result without a check, which is how a regression slips in.
