When I joined Mintlify, my first real project was to help refactor one of the oldest areas of the codebase, the API reference pages. There were some concrete performance improvements we wanted to make, but more than any immediate customer-facing gains, the biggest goal was to make the code easier to maintain and extend.

However, we’re a startup; we don’t have endless time to write code purely for the sake of having beautiful, elegant artifacts. So how do you strike the balance between taking the time to Do It Right and actually getting something done?

I don’t think there’s a silver bullet answer, but I think there are a few things that helped guide us to a really great result.

Unit tests are worth their weight in gold when refactoring

One huge advantage we had going into this refactor was that while the old version was a rat’s nest of layered-on complexity and hastily-appended edge cases, almost everything that had been added had some kind of unit test to capture the bug which had originally prompted the change.

These changes were not always particularly well-documented, if at all, which meant that sometimes we had to accept that we didn’t know exactly why some output needed to look a certain way—but we did know what that certain way was.

We set a goal of paying this work forward, writing copious tests for our new functionality; not only will this be useful for future devs, it was hugely useful in the final days of the project as we were shipping a little more frantically trying to get things over the line!

Write for your future self

When you’re trawling through two-year-old code, wondering how the hell a thinking human being could have possibly written such insanity, it’s helpful to remember all the times that you have written ridiculous code that someone had to clean up in the past.

The times that we found components which left our jaws on the floor, or hacks that left us in disbelief—those are the times we put the most effort into our refactors.

When you’ve had to fix bugs in someone else’s code at two in the morning, and you finally get a chance to set things right, you’ve gotta take the opportunity to think of the next dev at 2am!

Refactored software has the same quality bar as the old software

Regardless of any crowdthink about “move fast and break things,” I wouldn’t feel right about shipping software that I didn’t think worked properly.

However… if the old software was a little crunchy around the edges, you do get a little permission to accept that some things might not work perfectly in v2, either.

When you’re drained and getting close to the end of a project, it’s important not to let perfect be the enemy of the good; if there’s one place you know you can safely cut a few corners, it’s the place where the corners have already been cut!

---

If you find yourself in a position to be refactoring code for the explicit benefit of future developers, I really do believe you should be grateful to have found yourself in such a position, and take every advantage to create something you’ll be proud to look back on. Just remember that it doesn’t matter to anybody until you actually get it shipped!