Refactoring Without Fear

Behavior Preservation First

The defining characteristic of refactoring is that it is behavior-neutral. If the observable behavior of the system changes — even if it becomes “better” — you are not refactoring; you are rewriting.

To ensure behavior preservation, we rely on safety nets. In the Nex philosophy, these safety nets are not just external tests, but internal contracts. A refactor is successful if: 1. Contract checks pass: The require and ensure clauses of the refactored modules are still honored. 2. Regression tests pass: The suite of automated tests still produces the same results. 3. Parity is maintained: On a representative sample of inputs, the new structure produces the exact same outputs as the old structure.

Without these safety nets, refactoring is guesswork. With them, it is a controlled transformation.

The Incremental Refactor Pattern

The most effective way to reduce the risk of a refactor is to break it into small, verified slices. A “big bang” refactor — where a developer spends a week rewriting a major component and only tests it at the end — is a recipe for disaster.

A more reliable sequence is the Incremental Refactor Pattern:

1. Capture current behavior: Before touching the code, ensure you have a baseline of tests or contracts that define what “correct” looks like.
2. Extract the extension point: Introduce an interface or a boundary that separates the code you want to change from the code that uses it.
3. Move one responsibility: Perform the smallest possible structural change. This might be moving a single method or splitting a single class.
4. Run parity checks: Verify that the system still works exactly as it did before the move.
5. Iterate: Repeat the process until the desired structure is achieved.
6. Remove the old path: Only once the new structure is proven stable do you delete the legacy code.

This pattern minimizes the “distance” between a mistake and its discovery. If step 4 fails, you know exactly what caused the regression: the small change you just made in step 3.

From Problem to Refactored Design

Consider the requirement:

“The Search Service has grown too large. It now handles both document retrieval and relevance ranking. We need to split these into two independent services.”

A naive approach might be to create two new classes and move code between them. A disciplined approach follows the incremental pattern:

1. Baseline: We verify that the current Search_Service.query() produces known results for a set of test queries.
2. The Extension Point: We define a Ranking_Service class but keep it empty for now.
3. The Move: We move the ranking logic from Search_Service to Ranking_Service.rank(). The Search_Service now calls Ranking_Service.rank() instead of doing the work itself.
4. Parity: We run the same queries as in step 1. If the results are identical, we have successfully refactored the logic without breaking the behavior.

The outward contract of the search system — “given a query, return ranked results” — remains unchanged. The internal structure — “how those results are retrieved and ranked” — is now more modular and maintainable.

Implementation in Nex

In Nex, we can use the Refactored_Knowledge_Service to demonstrate how internal decomposition preserves the external contract.

-- Original (Legacy) Service
class Legacy_Knowledge_Service
feature
  query(q: String): String
  require
    query_present: q /= ""
  do
    -- Tangled retrieval and ranking logic
    if q = "graphs" then
      result := "DOC:G-1"
    else
      result := "DOC:GENERIC"
    end
  ensure
    non_empty: result /= ""
  end
end

-- After Refactoring: Two focused services
class Retrieval_Service
feature
  retrieve(q: String): String
  do
    if q = "graphs" then
      result := "CAND:G-1"
    else
      result := "CAND:GENERIC"
    end
  end
end

class Ranking_Service
feature
  rank(candidate: String): String
  do
    if candidate = "CAND:G-1" then
      result := "DOC:G-1"
    else
      result := "DOC:GENERIC"
    end
  end
end

-- The Refactored Orchestrator: Same contract as Legacy
class Refactored_Knowledge_Service
create
  make(retrieval: Retrieval_Service, ranking: Ranking_Service) do
    this.retrieval := retrieval
    this.ranking := ranking
  end
feature
  retrieval: Retrieval_Service
  ranking: Ranking_Service

  query(q: String): String
  require
    query_present: q /= ""
  do
    let c: String := retrieval.retrieve(q)
    result := ranking.rank(c)
  ensure
    non_empty: result /= ""
  end
end

The Refactored_Knowledge_Service.query() has the exact same require and ensure as the legacy version. Any client using the legacy service can switch to the refactored one without knowing that the internal implementation has changed from a single tangled block to a clean two-service architecture.

Parity Checks in Practice

Each running system has a typical refactor, and each needs a parity check suited to it.

The goal is to improve the “how” while strictly preserving the “what.”

Where Refactoring Fails

The “Big Bang” Temptation. As we noted, trying to fix everything at once is the fastest way to break a system. The remedy is to force yourself to work in slices that can be committed and verified in a single hour.

Missing Parity Checks. Assuming that “the tests passed” is enough can be dangerous if the test suite is sparse. The remedy is to use real-world data (or high-fidelity samples) to compare the output of the old and new paths before making the switch permanent.

Early Deletion. Deleting the legacy code before the new path has survived a production workload is a common source of “no-way-back” incidents. The remedy is to keep both paths alive for a short period — perhaps behind a feature flag — so that you can roll back instantly if a subtle behavioral difference is discovered.

Part VIII established the discipline of growth. In Part IX, we look toward the future: how these engineering principles apply in an age where AI assistants are helping us write and review the code we build.