Playbook · Technical debt and legacy code

Updated

When is refactoring worth it?

Code refactoring is worth it when it makes the next changes you have planned faster or safer. If the code works and nobody needs to change it, refactoring it costs time and earns nothing back.

Across 39 production codebases, low-quality code had 15 times more defects than high-quality code, and fixing an issue in it took on average 124% more time.
Source: Tornhill and Borg, Code Red (International Conference on Technical Debt 2022), Mar 2022

What refactoring is

Refactoring changes how code is written without changing what it does. Users see nothing, which is why it is so hard to get a budget for. The team sees code that is easier to read, test and change. If behaviour changes along the way, it is a rewrite or a feature, and should be reviewed as one.

When code refactoring is worth it

  • The code is in a part of the product you change every week.
  • A planned feature would be faster to build on cleaner code than on the current one.
  • The same bug keeps coming back from the same place.
  • Only one person understands the code, and they are busy or leaving.
  • Adding types: a large JavaScript codebase gets messy fast unless every developer is careful. Moving to TypeScript, or adding JSDoc types, is often the refactor that pays back most.

When refactoring is not worth it

  • The code works and nobody needs to touch it. Ugly is not a business case.
  • The product or the feature will be replaced soon.
  • There are no tests, and you would be refactoring blind. Write the tests first.
  • The real problem is the infrastructure. The next section has an example.

What refactoring cannot fix

On one project the server kept timing out. My first view was that the Heroku dynos were too small for the number of users. The client wanted a fix in the code first, so we added caching and tuned the PostgreSQL and Neo4j queries. That work was worth doing on its own. But in the end we still upgraded the dynos. Clean code does not make a small server bigger.

How to refactor safely

  • Tests first, on what the code does today.
  • Small steps, one per merge request, each one shipped before the next.
  • Keep refactoring and new features in separate merge requests, so a reviewer can tell them apart. A bug hides well in a diff that claims to change nothing.
  • Refactor the part a ticket already touches, instead of a cleanup project nobody signs off.

Refactor or rebuild

At some point a module is so messy that refactoring it costs more than building it again. At Mom Software, the Angular 10 app followed no pattern and carried a lot of dead code and unused libraries. Refactoring it piece by piece would have kept all of that. We started again on a Fuse template and moved the old code over module by module instead.

Read next

Sources

Start

Tell me where the product is stuck.

In 30 minutes we look at where things stand, what you need from a CTO right now, and which option fits. Either way, you leave with a clear next step.

How the call goes

  1. 01You tell me about the product, the team and the next 6 months.
  2. 02I ask about the code, the stack and what keeps breaking.
  3. 03We pick the option that fits, or agree that none does.

09:00 to 20:00 CET

Founding rate: the first 3 clients get 20% off, in return for a named testimonial and a case study. On a monthly plan, the 20% applies to the first month.