I have a weird superpower: I can read the manual.
I don't mean "skim the docs and guess." I mean I'll grab the README, chase links, pull up arXiv, hit Wikipedia, and then go spelunking through GitHub until the codebase confesses what it's doing. I jokingly call it "the ability to RTFM," because that's basically it.
That skill saved me when I inherited a Django app at a startup that was literally running Python 2.6. The code was old enough to vote, and just as confused about its identity. Refactoring is how you turn that kind of project into something boring and predictable. Boring is the goal.
Refactoring without breaking behavior
Refactoring is restructuring code without changing what it does from the outside. Same inputs. Same outputs. Less chaos inside.
The fastest way to blow up a refactor is to start with vibes instead of tests. The second fastest way is to "clean up everything" and accidentally rewrite the product.
If there are no tests, I write a few before refactoring. I once refactored a payment processor without tests first. Broke production. Lost the client. Now I write tests even if they're ugly.
I like refactors that ship in small chunks. If you can't explain the change in one sentence, it's too big.
Before you touch anything: a quick assessment
Here's the checklist I run. I learned this the hard way after a client blamed me for a database issue that existed before I touched a single line. Now I document everything upfront.
- Code review for patterns: giant files, deep nesting, copy/paste logic, "utils.py" that's 2,000 lines.
- Pain points from humans: ask the team what they hate touching. That's your map.
- Dependencies: what internal modules depend on what, and what third-party libraries are glued in place.
- Docs and intent: sometimes the original design is in a doc, sometimes it's in a Jira comment from 2019. Still counts.
- Test coverage reality check: not "do we have tests," but "do tests protect behavior we care about."
Six refactors that pay rent
1) Modularize the blob
If you've got large_script.py doing everything, split it by responsibility.
project/
main.py
data_processor.py
api_client.py
report_generator.py
Then main.py becomes boring orchestration. Boring is good.
2) Use patterns only where they reduce pain
Don't use patterns because they're cool. Use them when they solve an actual problem you have right now.
Factory is a good one for legacy code that has a pile of if animal_type == "cat": ....
from abc import ABC, abstractmethod
class Animal(ABC):
@abstractmethod
def speak(self) -> str: ...
class Dog(Animal):
def speak(self) -> str:
return "woof"
class Cat(Animal):
def speak(self) -> str:
return "meow"
class AnimalFactory:
@staticmethod
def create_animal(kind: str) -> Animal:
return {"dog": Dog, "cat": Cat}[kind]()
Now adding a new animal stops being a scavenger hunt.
3) Update syntax to modern Python
Old string formatting is a smell. Not because it's morally wrong. Because it's harder to read.
print(f"Hello, {name}!")
The walrus operator is also handy in small doses:
if (value := data.get("key")) is None:
raise KeyError("Missing key")
4) Add type hints where they clarify intent
Type hints are documentation that your IDE can yell about.
from typing import Any, Dict
def process_order(order: Dict[str, Any]) -> float:
return float(order["total"])
No runtime change. Big readability win. For even better validation, consider using Pydantic to eliminate manual type checking.
5) Kill duplication aggressively
Legacy code loves twins.
def remove_rotten(items: list[str]) -> list[str]:
return [x for x in items if not x.startswith("rotten_")]
Then process_apples() and process_oranges() stop being 90% identical.
6) Fix error handling and logging
A legacy project with except Exception: pass is a project that wants you to fail. It's like the code is actively rooting against you. I found one once that had been swallowing database errors for three years. Three years of silent failures.
Use context managers and specific exceptions.
import json
import logging
logger = logging.getLogger(__name__)
def read_config(path: str) -> dict:
try:
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
except FileNotFoundError:
logger.error("Config missing: %s", path)
raise
except json.JSONDecodeError:
logger.error("Config is not valid JSON: %s", path)
raise
Now failures are visible, repeatable, and debuggable.
Tools I actually use
- Black (my favorite, though my last name is Prickett, not Black - I just like that it removes all formatting arguments from code review)
- ruff / flake8 for linting
- mypy once type hints exist
- VS Code refactors for safe renames and imports
The only strategy that works: incremental change
I've watched three different companies pitch the "big rewrite" and then spend 18 months building nothing. Meanwhile the old system keeps running, bugs and all, because at least it works.
Refactoring never ends. Pick whatever is making your team swear the most. Add some tests. Fix one thing. Ship it. Do it again next week.
You'll have 50 ideas for improvements. Write them down so they stop bouncing around your head. Then pick the one thing that will make tomorrow less painful and do that. The rest can wait.
This is how you avoid the technical debt trap without falling into the big rewrite trap. Make sure your code lives in version control so you can roll back if something breaks.
Sethers