Skip to content

Refactoring Guidelines

  • Never mix refactoring commits with feature or bug-fix commits — keeps history readable and reviews focused.
  • Tests must pass before and after every step; if tests break, you changed behavior.
  • Work in small, committed steps — each commit is one coherent, passing refactoring.
  • Refactor before adding a feature, not during (Fowler: "make the change easy, then make the easy change").
  • Boy scout rule: leave it cleaner than you found it, but stay within the scope of the current task.
  • Rename relentlessly — renaming to reflect true intent is the highest-value, lowest-risk refactoring.
  • Extract when code needs a comment — if a block needs a comment to explain what it does, extract it into a named function.
  • Never speculate — only refactor to support a current, concrete need; YAGNI applies here too.
  • For large structural changes: use the strangler fig pattern — incrementally replace old code; avoid big-bang rewrites.

Directives

  • Never mix refactoring commits with feature or bug-fix commits
  • Tests must pass before and after every refactoring step; if tests break, behavior was changed
  • Work in small committed steps; refactor before adding a feature, not during
  • Rename relentlessly to reflect true intent
  • Extract into a named function when a block needs a comment to explain what it does
  • Only refactor for a current concrete need (YAGNI); use strangler fig for large structural changes