Working code isn't enough. Each minimal patch adds a special case, a flag, or a dependency, and complexity grows one small change at a time. If you're not making the design better, you are probably making it worse.
Before editing
- Read the design around the change: the module's interface, its callers, and the conventions in use.
- Ask: if this module had been designed from scratch with this change in mind, what would it look like? Sketch that shape.
- List where the current structure fights the change. Typical signs: you would need a new flag or boolean parameter, a parameter threaded through layers that don't use it, knowledge duplicated in a second module, or an
iffor one caller.
Choose the path
- Ideal: refactor toward the sketch, then make the change. Default to this when the refactor stays close to the code you're touching. Aim to spend about 10–20% extra effort on it.
- Nearly as clean: if the ideal is too costly, look for a variant that gets most of its benefit for a fraction of the work.
- Tactical, with debt recorded: only under a real constraint, such as a deadline or a cross-team incompatibility. Name the debt explicitly (a TODO with the reason, or an issue), never silently.
While editing
- Absorb the change into the normal path instead of adding special cases.
- Pull new complexity down behind the interface rather than exposing it to callers.
- Fix one nearby design imperfection when it's cheap.
- When in Rome, do as the Romans do: follow existing conventions. Change a convention only when both are true: you have significant new information, and it's worth updating every old use. Then leave no trace of the old one.
After editing — check the diff
- Did the change add a special case, flag, config knob, or pass-through parameter?
- Is any design decision now known in two places?
- Are comments near the change stale? Update them in place.
- Is the "why" (a subtle bug, a workaround) only in the commit message? Put it in the code.
- Is any debugging code or stray TODO left behind?
Too far
Don't turn a small fix into an unrelated rewrite. Refactor only what the change touches or what directly blocks it, and propose larger cleanups separately.
Output
Make the change, then report a short design delta:
Design: better | same | worse — one line why
Refactored: <what, if anything>
Debt: <recorded shortcuts, or "none">