Refactoring Legacy Code: A New Hope

The Quest Begins (The “Why”)

The reporter vividly recalls the first day they opened the legacy repository at their last job. The README read simply, “Good luck.” Inside, a monstrous 5,000-line codebase awaited, a mix of PHP, JavaScript, and some bash, written during a caffeine-fueled all-nighter. Each attempt to add a minor feature felt like stepping on a minefield.

A tiny change in one line often triggered silent bugs elsewhere, sometimes weeks apart. The root cause? Global state. A singleton called Config contained everything from database credentials to feature flags, while a logger called Log was imported ubiquitously via `require_once('logger.php');`. Functions accessed these globals, altered values, and left behind side-effects that were impossible to trace.

Writing unit tests required bootstrapping the entire application, waiting for the container to spin up, and hoping no test would inadvertently flip a feature flag for the whole suite. Debugging a null-pointer that only appeared when a specific CSV file was uploaded required three hours of effort. The reporter felt like a superhero who'd lost their cape—frustrated, embarrassed, and desperate for a better approach.

The Revelation (The Insight)

A turning point occurred when the reporter stumbled upon "Working Effectively with Legacy Code" by Michael Feathers. He introduced the concept of seams—places where you could insert tests or change behavior without editing the original code. The simplest seam, according to Feathers, is explicit dependency passing: instead of reaching for global variables, you pass required objects as parameters. By eliminating singletons or static imports, three significant benefits emerge:

Transparency: It becomes evident at a glance what a function needs to perform its task.

Testability: You can supply fake loggers, mock configs, or in-memory databases without bootstrapping the entire app.

Safety: Mutating a passed-in object is now obvious; accidental side-effects on other parts of the system holding references to the same global become apparent.

In essence, the greatest practice that transformed the reporter's coding habits is "Replace global state with explicit dependencies." It's not a fancy pattern, but a mindset shift that makes every line of code easier to reason about.