Refactoring 102

In my previous article, I talked about the most important, yet often over-looked, phase in refactoring: Doing research. But that article didn’t cover the rest of refactoring so I thought it only fair to write a second article with suggestions about the rest of the process.

Refactoring usually involves changing a lot of lines of code which can make pull requests (PRs) difficult to review, confuse source code management (SCM) tools, and throw Fear Uncertainty and Doubt (FUD) onto your changes. If a problem shows up in a release containing you refactor, it is only natural for project managers as well as team members to suspect your refactoring as the source of the problem. They might immediately suggest that all your hard work be reverted “until later” (which really means “probably never”), and with good cause! No one’s perfect and the more lines of code you change the more opportunities to make a mistake. The following suggestions are meant to help you robustly refactor and quickly determine if your changes are to blame if a problem should arise.

1. Be Functional After Every Step

This might take a little more work, but if each commit along the road of refactoring is meant to maintain functionality, then when a problem does arise, different levels of the code can be checked out and tested for the bug.

2. Make PRs Frequently

Making frequent pull requests will make each PR easier for reviewers to confidently approve. It also means that other developers can start utilizing your new code structures as soon as possible. There’s nothing worse than getting done with your refactor only to realize that while you were refactoring off in your own little world, development continued on the old code base making merging very difficult.

3. Be Patient

For me, refactoring is best done as a secondary task. Chances are good you will be held up for a day or two waiting for a PR to get approved and merged. In my experience, moving too fast during a refactor can end up generating a lot of extra work as suggestions on that PR you made a couple days ago can have ripple effects on the work you’ve done since then. So relax and return to implementing function in some piece of unrelated code and let the code review process work its magic.

4. Make Non-Functional Changes First

Whitespace changes or name changes (to bring code up to date with the latest coding standard) can end up touching tons of lines. These changes will usually be large but also non-controversial. Get them out of the way, even if it means making changes to lines that you later plan to replace, doing this step first is worth the slight overhead. Doing this first will help you with avoid the temptation to make these changes as you're making functional changes which you really want to avoid. (Make a PR.)

5. Code Shuffling and/or File Renames Atomically

Reorganizing functions into new or existing files, or renaming files should be done atomically. In other words, do not combine renaming a file with changes to the actual contents of that file. At least do this as a separate commit and probably even better as its own PR if you are changing a lot of files. Keeping the code as similar as possible as it gets shuffled around gives the code review software (and your teammates who are doing the reviewing) the best chance of determining what you did which makes for simpler, and therefore quicker, code reviews. (Make a PR.)

6. Plan, Divide, and Conquer Functional Changes

Divide functional changes into intermediate steps. This might require a little extra work but if you are going to switch from functional programming to object-oriented (for example), or from function pointers to templates, there will be a possibility of introducing bugs. Try to make foundational code changes first. For example create your objects but keep the methods the same as the original functions. This can help you quickly find a bug if one arises or, if you do have to revert some changes, if you can keep the foundational changes then work can continue with a majority of your refactor instead of the metaphorical baby being thrown out with the metaphorical bath water.

Conclusion

Please consider these suggestions the next time you see a crusty piece of code that is just ripe for a refactoring. Together, we programmers can take the fear out of refactor... which just leaves “ctor”... that doesn't make any sense... anyway, you get the idea.