How To: Refactoring – A workflow to refactor safely

This is part 2 of a series on refactoring, you should also read part one where we introduce refactorings and why you should do it

Doing a refactoring in any BIG project can be a frightening experience, you know that by  touching any part of it could introduce a bug and so it’s hard to justify changing it just for the sake of “aesthetics”. But fear not! if you apply your refactoring following a proper workflow you won’t risk doing any big damage and, as we said in the previous article, it’s better doing this sooner than later so that your project doesn’t become a big hairy mess.

Refactoring workflow

I’m a big proponent of the checklist manifesto and that is probably a topic for another time, but a lesson we can apply right now is that having a bit more structure in our methodology will go a long way. When tackling any refactoring we should follow this quick 4 steps process:

  1. Check-in
  2. Verify
  3. Edit
  4. Confirm

This is easier said than done, but is really powerful so you should keep to it. Now let’s dive in detail into each step.


Since our objective is to do a refactoring as safely as possible we have to start from a safe place. To get there, all we need to do is to check in (commit) our current code base to our favorite versioning system so that if necessary we can quickly come back in time and restore the version previous to any refactoring.

If you don’t use a versioning system at your current workplace then this step can be replaced with these:

  1. Get Up
  2. Calmly walk toward an exit
  3. When you are out of the building start running
  4. Never come back


As we said in the previous post, before doing a refactoring you have to check that you have working software. You do this in this step. The best way to make sure that your code does what it is intended to do is by running a comprehensive test suite which will probably be a lot of unit test with a bunch of integration and E2E test mixed in. The second best way is by writing a bunch of characterization test for the parts of the code you intend to modify. You can learn how to build your golden master in this post.

The third best way to do it (known also as the worst way to do it) is by doing a manual check. This is probably what most junior developers do and it sounds quick. But it isn’t reliable since humans tend to forget important things when you repeat a task many times. If you are following this workflow you will be doing these check many times over so better let the computer do it for you.


Now things get interesting. This is the step you all have been waiting for.

Refactor all the things

Well… actually, more like

Refactor a thing

I know it isn’t as fun as going wild with refactoring, but we aren’t going for fun, we are going for safe, so you should do one refactoring at a time.


Now this is just the second step repeated. Since you modified the code base you don’t know if it works anymore. I know that you personally are a really good programmer that would never ever write a bug, but just for the sake of it don’t skip this step. BTW since you are a great programmer you have automated this process in the verify step, so there’s really no need for skipping it, just run your test suite and move on.

Now that you are certain that it works, you can repeat this cycle by starting over again with a check-in.

Extra Tips

  • Small Changes: If you need to do a big refactor it is better to do multiple small changes, so that it is harder to break stuff;
  • One at a time: Repeat the workflow for each change you make, don’t try to multi-refactor, it won’t end well;
  • Make a later list: If you are in the middle of a refactor and see something else you would like to change, better add it to a TODO list and tackle it after you have finished what you where doing;
  • Frequent check-ins: if you are working in git this is easier, you keep committing to your local branch and when you are done you push to the main repository;
  • Code review: Even if your tests pass, better have another pair of eyes to have a look. This way if you missed something in your refactorings or something could be improved you are already set to fix it;
  • Add Tests: While you are at it, you are bound to end up in places that don’t have many tests covering it. In the verify step take your time to add a few more tests, this is a gift that keeps on giving;
  • Keep tests clean: Test code should be kept to the same hight standards as production code, so in this process you should refactor also your tests to keep them clean;
  • Come visit this site often, with this series we are going to show you some how to identify most code smells and how to refactore them, if you don’t want to miss an article subscribe to our rss feed or to our mailing lists

Author: Maurizio Pozzobon

Maurizio has 5+ years developing solutions in the insurance industry. He is passionate about doing the right thing right, so he works in a tight loop with his clients to deliver the best solution possible.