Deta

The Art of Refactoring Legacy Code Without Inviting Disaster

Refactoring isn't just about tidying up functions, it's about the order of thinking: understand context, add a safety net, and bring empathy through small PRs.

September 8, 2026 · 4 min read · #Software Engineering #Clean Architecture #Code Review #Kotlin Multiplatform

A few days ago, my tech lead sent a message in our team chat that's still sitting in my head:

"…we can start look over the tests and consistency of code and architecture, are there pieces which should be moved around following the Clean Architecture already going on? Where are the technical debts? First thing should be for us to clean up the project to more easily grasp what is going on, but to do this we also need to be wary not to break anything, hence write tests first and make good arguments in PRs to why the changes are made, and make them PRs small and easy to digest for the developers already in the project."

The code itself isn't that complicated. What kept nagging at me was the order of thinking they emphasized before we even touch the keyboard.

The context: a Kotlin Multiplatform library that's been around for a while, powering Android, iOS, and backend, worked on by a good number of people. The team is slowly migrating toward Clean Architecture.

Faced with messy legacy code, most developers' first reflex is to clean it up right now. Without the right order, refactoring turns into a disaster.


1. Understand First, Change Later

Before arguing about clean code, test coverage, or the ideal architecture, ask yourself first: what was this code built for, and who uses it?

This question gets skipped the moment our technical ego gets triggered by ugly code. Without understanding the business context and the past trade-offs behind that code, our refactor risks undoing design decisions that were made on purpose.

Once we understand how the system talks to itself, we can figure out which tests are dangerously missing, where the inconsistencies actually live, and which components genuinely deserve to move.


2. Mapping Technical Debt Precisely

Like the message hinted ("Where are the technical debts?"): saying "this project is full of technical debt" is cheap and easy. The hard part is pointing at it precisely.

Useful technical debt has a clear address. Which part violates the architecture boundary? Which file hides a side effect? If we can't map its location in detail, we don't understand the problem yet.


3. First Goal: Make the Code Easy to Understand

Forget the ambition of 100% Clean Architecture in one sprint. That target almost always ends in failure or burnout.

Set a realistic goal instead, the same one from that message: leave the codebase easier to read than when you first opened it. Once the flow is transparent, every future fix gets cheaper to make.


4. The Safety Net: Tests First, Refactor Second

Our main goal is to clarify the flow without changing behavior. The risk of breaking something already working in production is real if the order flips.

  1. Write tests first to lock in the current behavior.
  2. Do the refactor, using those tests as a safety net.
  3. Include a strong argument in the Pull Request description.
  4. Split the PR into small chunks.

In practice, people rush to clean up code and only panic-write tests once the app crashes in a user's hands. Test-driven refactoring is insurance, not a formality.


5. Small PRs Are a Form of Empathy

The last point from that chat that stuck with me: a good Pull Request respects your teammates' time.

Refactoring isn't about making the code look nice to us. It's about making it easy for someone else to review, understand, and maintain down the line.

A giant PR that touches dozens of files at once usually gets rejected for being too confusing, or rubber-stamped because the reviewer got tired of scrolling. A small, focused PR with a clear rationale is the highest form of respect you can give a teammate.


The Takeaway

That message laid out an order of thinking that applies to any project with a long history: understand context, map the debt, write tests, refactor slowly, send a small PR.

The most valuable code improvement isn't a dramatic, sweeping rewrite. It's the small change the team can trust, and calmly build on once we've moved to the next task.

Comments