A few tips to get a refactor project scoped, pitched and shipped; all while demonstrating value to the company at each stop along the way.

Context

Codebases are constantly accruing technical debt. Through the mere state of existence, code becomes stale the minute it’s been committed. Patterns that were once in vogue become obsolete, newer versions of upstream dependencies are released, and the underlying technologies and infrastructure your code runs on can shift under your team’s feet.

At one point or another, codebases (or large parts of a single codebase) have to be reworked.

Whether your team is doing this out of necessity (“We have to migrate to Python 3 by EOY in order to upgrade to the next version of Django.”) or for the sake of quality of life improvements (“Man, it would sure be nice to rethink our data layer - it causes us never ending headaches.”), I’d like to solicit a few tips. These tips will help get your refactor project off the ground with the buy-in necessary to allow you the space and time necessary to see the project to completion.

Timing

Timing is everything - don’t introduce a refactor initiative in the middle of another project. That’s tantamount to pulling your team in multiple directions which will drive your manager and PM nuts.

Find a nice quiet time after a feature-y project has wrapped. Bake in some downtime during the end of that project to start scoping the work you and your team would like to accomplish in a technical clean-up.

Planning

Before approaching cross-functional team members and your manager with a refactor, it’s always smart to have a plan and timeline in place. Figure out the difference between must-have and nice-to-have. The outside world can’t easily see the value in refactor work, so keep scope as tight as possible when planning (ie: what can you get done in phase one, and what can you group nicely into a phase two project down the road).

Buy-In

If you’ve found a window and done enough prep-work to get this on the table you should be feeling great. Buy-in is all about contextualizing the pain points that this technical debt is causing and the benefits that can be captured if the team can get the time to address the problem.

If pain vs reward is obvious, your scope is tight and the team is in between projects - getting buy-in should be a slam dunk.

Development

You’ve secured approval and the team is ready to get to work. Go back to that rough timeline and break the project into smaller, more estimable components. Connect with your technical lead to get a true sense of the level of effort required to complete the project.

Cut anything that isn’t a priority and move it to another logical refactor project that you can tee up as “phase two”.

The Cherry On Top

Assuming all went well and your team delivered on time and under budget, now is the time to lean into that success and share it with others.

Most refactors are technical in nature, so how do you make this digestible by the rest of the organization?

It is wholly appropriate to share this type of work at a demo day (or similar ritual). The goal here isn’t to show code, but to contextualize to the rest of the organization the motivations for, and benefits of, refactoring away that technical debt.

Revisit pain points, discuss short-term + long-term benefits. Share what this project meant – not only for the development team, but how this work impacted the bottom line of the company.