Skip to content

Refactoring at scale

Refactoring a large codebase fails for a predictable reason: you change something without knowing everything that depends on it. Understand's job in a big refactor is to make the blast radius visible before you touch code, and to prove afterward that the change actually improved things. This page sequences the how-tos into a safe workflow.

1. Pick the right targets

Don't refactor by intuition. Let the data point at the worst offenders:

2. Understand the blast radius

Before changing an entity, learn who depends on it. This is where Understand earns its keep:

  • The Information Browser lists every place an entity is used and everything that calls it — expand Called By to see the full reach.
  • A call or dependency graph shows the same reach visually, so you can spot the seams where a change is contained versus where it ripples.
  • For file- and subsystem-level impact, use dependencies.

3. Refactor safely

For the mechanical edits, Understand's editor provides refactorings that use the parsed model rather than text matching — Rename, Inline, and Extract — so a rename updates real references, not same-named strings. See Refactor safely.

4. Lock in the new structure

A refactor that isn't enforced erodes. Once you've established the intended structure, make violating it fail:

5. Prove it improved

Close the loop by measuring before and after:

Refactoring for complexity specifically?

If the whole point is to drive complexity down, see the complexity-focused tour in Finding & reducing complexity.