Refactoring 101

We programmers call it “refactoring” or “paying our technical debt” because the word “rewrite” strikes dread in the hearts of project managers and causes them deny us the permission to do it. It is something that many novice programmers immediately want to do to every new piece of code they encounter, and therein lies the danger. Refactoring isn't bad, needlessly refactoring is.

However, call it what you will, refactoring is to programming as defragmenting is to hard drives. It’s a healthy part of a program’s life cycle. It improves the efficiency of us programmers, increases our willingness to work in those previously-abandoned areas of code, and, let’s be honest, we enjoy doing it. I’m a big advocate of refactoring. (A few months ago I had the pleasure of refactoring a couple repositories.)  In my opinion, the most important (and yet overlooked) phase of a successful refactor is the first one: Do Your Research

Do Your Research

So what does it mean to do your research? I’ll break it down into several steps and discuss each in more detail. Don’t be daunted by the word “research”, what I am suggesting should not take more than a few hours and might save you days or even weeks of work.

Step 1: Read the Repo

You need to be aware of who wrote the code you are wanting to refactor and when they wrote it. No one wants to hear you refactored code they just got done writing and even reasonable program managers should be skeptical of the need to refactor code that was written recently. (As I will discuss more later, it is important to have the support of the team when refactoring so alienating the original author or making a bad impression on the program manager won’t help your cause.)

Use revision control to do this initial research. Spend 30 minutes reading some of the recent commit history. You might realize that the code is complicated for a reason and that a refactor will be more than you are wanting to take on. Determining this before talking with anyone will save you the embarrassment of getting in over your head.

Even if you are confident you can handle the refactor, reading the commit messages can help you understand the edge cases (e.g. bugs that have already been worked through) and enable you to have an intelligent conversation which is the next piece of research you should do.

Step 2: Talk to the Original Author

(If the original author is not available, find someone whose opinion you respect, who has at least some experience with the code.)

This might seem like “asking for trouble” but the original author (or experienced team member) is a very valuable resource and it is a foolish-novice mistake to not utilize them if they are available. This is not a time to "do now and ask for permission later". You need to understand why they designed it as they did and try to gauge their acceptance of the idea. Seek them out. Explain how you think the code could be improved and clarified by refactoring.

Experienced developers recognize that the code they wrote gets out-of-date: perhaps a new open source package has become available that could do much of the heavy lifting, or perhaps unanticipated edge cases have been fixed with bandaids for the sake of time during a shutdown period and the time is now right to fix them with a more robust solution. The original author might welcome the idea of the code being refactored.

They might be happy to pass “ownership” of the code to someone else, and besides all that, their acceptance of the idea is probably necessary in order to get the changes merged into the repo. Changes made without input from someone else on the team tend to be removed without input from you. What good is it to do all that work just to have it all die in a firestorm during the pull request (PR).

Step 3: Listen to Them

You've spent the time to do the research, now utilize it! Regardless of who you had the discussion with, here are some possible outcomes:

• In the course of explaining your vision you suddenly realize: It’s not that great. Sometimes you just want to rewrite something to use some whiz-bang new-shiny-thing you found. For example, you want to convert code written in C++ to Rust, or you’ve been dying to apply machine learning to some problem regardless of whether it will really improve the program in question. Be open to the possibility that The Right Thing is to leave the code alone.
• Your colleague agree that the code needs refactoring... and they already have a local branch where most of the work has been done. (You don’t get credit for doing the same work as someone else, so finding this out early saves you time and frustration.)
• Your colleague points out some edge cases the current code covers that you will have to figure out how to handle in your refactoring. This doesn’t mean you shouldn’t do it, it will just help you do it correctly. Nothing reverts a refactor faster than when it introduces new bugs on already-solved problems.
• Your colleague is enthusiastically on-board with the idea and they give you additional ideas of what to change.

If, after the redesign discussion, your colleague thinks you should not refactor this code, at least not right now, then don’t. Respect their opinion. In doing so you will earn their trust, and later, when there is something they would like to see refactored, they might ask you to help do it.

If, after doing this research, you are still going to refactor the code, you can proceed with the confidence that comes from having a respected advocate in case you need to defend your actions to your project manager or other team members.