Successful refactoring projects - Set the right goal

Matthias Noback

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:

  • Being able to upgrade to PHP 7
  • Being able to run tests without an actual database
  • Being able to rely on static analysis for support during development

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:

  • Being able to keep the software running for years to come
  • Being able to develop new features faster
  • Being able to release fewer mistakes to production

Alignment

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):

  • What are the benefits they’ll notice, e.g. being able to work faster, release fewer mistakes, those are really good selling points for a refactoring project.
  • Explain that you can work on this for just a few hours each week and still get those benefits. This can take away the fear that this may be one of those endless projects that have to get cancelled in the end. It forces you to think about refactoring steps, and being able to stop (and start) at any time.
  • What are things you’ll unlock for the company, e.g. by deploying your application as a Docker image, deployments will be a single-step process, which finishes in a matter of seconds.

Conclusion

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!