Successful refactoring projects - Set the right goal

Written by Matthias Noback / Original link on Feb. 18, 2021

Refactoring is often mentioned in the context of working with legacy code. Maybe you like to define legacy code as code without tests, or code you don't understand, or even as code you didn't write. Very often, legacy code is code you just don't like, whether you wrote it, or someone else did. Since the code was written the team has introduced new and better ways of doing things. Unfortunately, half of the code base still uses the old and deprecated way...

The need to be consistent is very strong in me, and from what I see, in many developers. And so we get started and improve every bit of code everywhere. We become frustrated if we don't "get" time for this work from our managers ("they don't get it"), or if we can't finish it; look at all this code, it's so outdated!

Consistency is a bad refactoring goal

I've had this experience many times, and it made me give up on consistency as a refactoring goal. Not because consistency isn't good. It is, because the uniformity of a code base makes it easier to contribute to it. Fewer surprises means you'll make fewer mistakes. The problem is consistency as a refactoring goal:

  1. It's an all-or-nothing goal. Either the code base is consistent, or it isn't. When you start the project, you have to finish it, or you'll feel unsatisfied. This conflicts with what we established in the previous post: prepare to stop at any time.
  2. It doesn't serve a goal for other stakeholders. Which means it will be very easy for managers to pull the plug on the refactoring project, if they find out it's costing them valuable development hours.

Higher refactoring goals

When it comes to refactoring projects, the development team (or sometimes just one developer) is often the primary stakeholder. Some common refactoring goals that developers have are:

When discussing these goals in a meeting with business stakeholders, they will downplay them because they don't seem relevant for their own cause. They aren't right, of course, because what's great about these "developer-oriented" goals is that they actually serve higher goals, goals that also serve business stakeholders:


Very often when I find my refactoring projects being postponed or blocked, I realize it's because I didn't explain the higher goals. What is often really useful is to talk to other stakeholders or decision makers (and pardon the management speak):


In summary, for a successful refactoring project you need to be able to stop and continue at any time. Establish refactoring goals that serve higher goals. Explain to business stakeholders that your development goals have benefits for them too.

Once the refactoring project gets the green light from the team, the next task is to determine refactoring steps. To be continued!


« Make it a Blade + Alpine Component - Technique #1: A URI Hash Toggles the Modal »