Refactoring

What it is

Refactoring is changing the internal structure of code without changing what the code does for anyone who uses it. Names, function boundaries and the layout of modules change; inputs, outputs and side effects stay exactly as they were. The verb is to refactor, and one such change is also called a refactoring.

Martin Fowler defines the term in his book Refactoring, and restated the definition on his website in 2004. As a noun, a refactoring is one change to the inner structure of software that makes the code easier to understand and less costly to change, while what it does as seen from outside stays the same. As a verb, to refactor is to carry out a sequence of such changes, with that outside behaviour unchanged throughout. Both halves matter. The purpose is a cheaper next change, and the constraint is that nobody outside the code can tell that anything happened.

Fowler draws the line sharply: “Refactoring isn’t another word for cleaning up code,” he writes on refactoring.com. It names one specific technique. He uses restructuring as the wider word for reorganising code by any means, including ones that do not preserve behaviour at every step. What makes refactoring a technique is its size. Each step is a small transformation that does little by itself and is unlikely to go wrong, and the whole system still works after every one. A long sequence of them can still add up to a large change in structure.

The steps have names. The catalogue on refactoring.com, which accompanies the second edition of the book, lists them with the older names they replace: Extract Function, also known as Extract Method, and its inverse Inline Function; Inline Variable; Rename Variable; Move Function; Split Phase, and dozens more. A shared name lets a developer say what a change was in two words, and lets a reviewer check it against a known recipe.

Why it matters

Software that succeeds keeps changing. New features and fixes are layered on top of each other, and each one tends to make the next a little harder, until, as Fowler describes it, adding anything new takes painfully long. Refactoring is the counterweight: it reshapes the code so that each addition does not bring complexity it does not need. Its return is measured in the cost of the next change, not in the look of the code.

That is why Fowler treats it as part of ordinary programming rather than a task that appears in a project plan. He names three moments. Before adding a feature, he checks whether the code is shaped to make the feature easy, and refactors first if it is not, which he usually finds quicker than forcing the feature in. After the feature works, he refactors the result into a shape that someone returning in a few weeks can follow without puzzling. And when he has to read unfamiliar code to understand it, he refactors so that the next reader does not struggle in the same place. The first of these has its own name, preparatory refactoring, and Fowler credits Kent Beck with the rule behind it: for every change, first reshape the code until the change is easy, which can be the hard part, and only then make it.

Refactoring also keeps risk low in a way that feature work cannot. Fowler passes on another of Beck’s metaphors, the two hats. While wearing the refactoring hat, every change preserves behaviour and the tests stay green throughout. While adding function, tests are added and existing ones break, which is more stressful and riskier. A developer who knows which hat is on knows what a failing test means: during a refactoring, it means the last step was wrong.

The same idea is how most technical debt gets repaid. The Google paper on hidden debt in machine learning systems lists refactoring code first among the ways to pay debt down. Tools help: many languages now have editors that automate common refactorings. Fowler counts such tools as valuable but not essential, and where they are missing he relies on small steps and frequent tests.

What it looks like in practice

Take a function, written for this article, that totals an order and prints a receipt in one place:

function printReceipt(order) {
  let total = 0;
  for (const line of order.lines) {
    total += line.price * line.quantity;
  }

  // print the receipt lines
  console.log(`Order ${order.id}`);
  console.log(`Total: ${total}`);
}

A new requirement arrives: the same total must appear on an invoice. Rather than copy the loop, the developer first refactors. Step one is Extract Function: the loop moves into its own function, named for what it computes, and the tests run. Step two extracts the printing the same way, so that a function name replaces the comment, and the tests run again. Step three is Inline Variable: the total variable is now used only once, so the call takes its place. After each step the program does exactly what it did before and could be committed on its own:

function printReceipt(order) {
  printLines(order.id, orderTotal(order));
}

function orderTotal(order) {
  let total = 0;
  for (const line of order.lines) {
    total += line.price * line.quantity;
  }
  return total;
}

function printLines(id, total) {
  console.log(`Order ${id}`);
  console.log(`Total: ${total}`);
}

Only now does the feature go in, and it is one line in the invoice code that calls orderTotal. Nothing in the three refactoring steps needed a new test, because nothing observable changed; the tests that already covered the receipt are what prove it.

Infrastructure code is refactored as well, and there the stakes are higher, because the names refer to running resources. Terraform’s documentation warns that, by default, giving a resource a new address in the configuration tells Terraform to tear down the one that exists and build a fresh one. Renaming aws_instance.a to aws_instance.web for readability would therefore replace a server. Since Terraform v1.1, a moved block records the old address instead, and the next plan updates the address without destroying anything:

resource "aws_instance" "web" {
  # (configuration unchanged)
}

moved {
  from = aws_instance.a
  to   = aws_instance.web
}

On earlier versions, the documentation points to the terraform state mv command for the same move. Either way the refactoring is only safe once the plan has been read and shows a move, not a destroy and a create.

Keeping such changes separate from feature work is easier when the history says which is which. The commit standard described in this site’s portfolio entry on holding four repositories to one history standard starts every commit message with a conventional prefix naming the kind of change, enforced by a commit-message hook. The page, on work carried out in July 2026, counts 26 refactors in the largest repository’s history beside 156 feature commits and 133 fixes. The same page is honest that the hook checks the format and not the content. A commit labelled as a refactor still has to be shown by its tests and its review to have left behaviour alone.

Where it goes wrong

Behaviour changes ride along with the refactoring. A developer tidies a function and fixes a bug in it in the same commit. When a test fails, nobody can tell which of the two caused it, and a reviewer has to read every line as a possible change in behaviour. Wear one hat at a time: refactor in one commit, change behaviour in the next, and if a test fails while refactoring, undo the last step instead of fixing forward.

A large restructuring is called refactoring. A branch spends weeks with the build broken while the code is “being refactored”. That is restructuring, in Fowler’s terms, and it carries the risk refactoring is designed to avoid. Break the work into steps that each leave the system working and can be merged on their own; where that is not possible, call it a rewrite and plan it as one.

There are no tests to show nothing changed. Behaviour preserved is a claim, and without tests it is a guess. Before touching code that has no tests, write tests that pin down what it does today, even where that looks wrong, and fix the oddities in separate changes afterwards. Fowler’s rule of thumb from his preparatory refactoring example applies here: whenever the urge comes to run the code and inspect its output by eye, write a test instead.

A rename in infrastructure code replaces the resource. A tidy new name in Terraform reads like a refactoring in review, and the plan quietly proposes to destroy a database and create an empty one. Record every rename and every move into or out of a module with a moved block, and treat any destroy in the plan of a change meant as a refactoring as a failed step.

An old moved block is deleted. Moved blocks accumulate, and removing them looks like housekeeping. The Terraform documentation calls it a breaking change: any configuration that still uses the old address would then get a plan that destroys the object rather than moving it. Keep the historical blocks, chain them when an object is renamed twice, and remove them only from a private module once everyone using it has applied the version that contains them.

Refactoring waits for a dedicated phase. A team that schedules a “refactoring sprint” for later keeps adding features to code that resists them, and a sprint planned for later is easy to cut when a deadline moves. Fowler’s advice runs the other way: refactor as part of each change, first to make the change easy and afterwards to leave the result clear, so that the work never needs a slot of its own in the plan.

Further reading

• Definition Of Refactoring — Martin Fowler’s noun and verb definitions, as given in his book.
• Refactoring — Fowler’s site for the book, with why refactoring is part of daily programming and the full catalogue.
• Extract Function — the catalogue entry for one of the most common refactorings, with its inverse and its first-edition name.
• An example of preparatory refactoring — Fowler reshapes his own code in small steps before adding a feature, and explains the two hats.
• Refactor modules — Terraform’s documentation on moved blocks, renames, splitting modules and why old blocks should stay.