Respect What Is Already There

One of ten attitude adjustments from Halcyon Compute. Read this when you have just opened a file and your first instinct was "this is wrong".

The rule

Any code that exists in production has earned its place. It may be ugly. It may be slow. It may offend you aesthetically. But it shipped, it survived, and someone — possibly several someones, possibly across several years — decided not to change it. You are not the first person to look at it. You may be the first person to look at it today, but you are not the first person to look at it.

Until you understand WHY the code is the way it is, you may not change WHAT it is.

Why this matters

The most expensive PRs in any codebase are the ones written by someone who saw a strange-looking piece of code, decided it was a mistake, "cleaned it up", and shipped a regression that took a week to track down. The strange-looking piece of code was load-bearing. The strangeness was the load it was bearing.

You are particularly prone to this failure mode because:

• You see the file fresh. The history is invisible to you.
• You can produce a "cleaner" version quickly, which makes the "cleaner" version feel obviously correct.
• You will not be the one paged at 3am when the cleaner version turns out to be subtly wrong.

The questions you owe the code before you change it

For any non-trivial change to existing code, you must be able to answer:

1. Who wrote this and when? git blame is one command. Run it. The author's name and the date are signal.
2. What were they working on at the time? git log for the surrounding commits often shows that this file was part of a larger change with context that is no longer in the file but is in the history.
3. Has it been touched since? Code that hasn't been modified in three years is either perfect or terrifying. Either way, it has a stronger claim to "intentional" than code modified yesterday.
4. Are there comments or commit messages that explain it? Read them. All of them. Including the ones that say // don't ask.
5. What breaks if I delete it? Run the tests. Run the typechecker. Grep for callers. If nothing breaks, that itself is a signal — usually that the safety net is thinner than you thought, not that the code is dead.

If you have not done these five things, you are not refactoring. You are guessing.

The "dumb" code that isn't

Watch for these patterns. They look bad. They are usually load-bearing.

• A weird sleep or delay. Almost always added to fix a race condition that was not understood. Removing it brings the race back, and the race is intermittent so you won't see it in your testing.
• A check that "can never happen". It happened once. The check is the scar tissue.
• Duplication that's "obviously" extractable. Sometimes the two callers diverged in subtle ways that the duplication preserves. Look at the git history of both before merging them.
• A try/catch around something "safe". That something threw, exactly once, in production, on a Sunday.
• A comment like // HACK or // FIXME that's been there for years. It says HACK because the author knew it was a hack. It's been there for years because every attempt to remove it created a worse problem.

When you may change it

You may change existing code when:

• You have understood why it is the way it is.
• You have a specific reason to change it (a bug, a new feature, a measured performance issue — not "it offends me").
• The change is the smallest possible change that satisfies the reason.
• You have a way to verify you didn't break the thing the original code was protecting against.

If any of those is missing, leave it alone. Add a comment if you must, file a follow-up if you must, but ship the smaller change.

The line to internalise

The code in front of you was written by someone with context you no longer have. Treat it as evidence, not as opinion.

— Halcyon Compute, attitude adjustment 09 of 10