Intro to Refactoring: Making Code Easy to Understand in 4 Steps

Refactoring is the process of organizing code to make it more readable and maintainable. There are a few steps you can take to refactor your code, if you don’t know where to start, or if you feel overwhelmed here are some ways to start. The goal is code that is easy to read and understand.

1. Name variables and functions well.

This is the easiest thing you can do that makes the biggest difference. Update str to be displayedProfit and i to be customer. The key is for the variable name to represent what is stored in it.

This especially applies to boolean flags—consider renaming the variable disabled to be isEnabled. As a rule of thumb, I like using is as a prefix for my boolean variables, and I like to use the most positive form of the word (isEnabled rather than isDisabled).

Function naming is also key. Functions are the verbs of code, and the code should reflect that. Be sure to name functions based on what they do rather than how they do it. Consider a function that checks a username to make sure all the characters are valid. You might call this function checkForInvalidCharacters. But a better name would be usernameIsValid.

2. Remove magic numbers.

There are a lot of magic numbers in our world—.06% sales tax, 21 years old, 12 inches, to name a few. Our code, however, usually lives outside of the context of the world around us. For example, if you’re calculating sales tax, the expression [price * salesTaxRate] has a lot more meaning than [price * .06].

3. Extract each step of logic into a function.

I have a function that gets to be more than 10 or so lines of code, it’s doing too many things. Maybe it’s verifying that the data is valid, remapping it to your database schema, and persisting it.

Creating functions around the different steps of the function gives you a chance to communicate with the next programmer using your code by assigning a verb to what is going on, rather than forcing them to draw conclusions based on the technical code.

4. Remove duplicate code.

Removing duplicate code is one of the first things that gets mentioned when refactoring comes up, but its the hardest to do, especially if it’s code you’re not familiar with already. Refactoring into smaller functions as you go is certainly a good way to avoid having duplicate code in the first place, but how do you find it once it’s there in a big mess?

I find that once I’ve gone through step 3 and extracted each step of the logic into separate functions, it’s a lot easier to discover duplicates and refactor them. My process looks something like this:

  • Write test cases for both features.
  • Change the code in both functions individually to make it look the same, if it doesn’t already.
  • Extract a common function from both features. Sometimes this means creating a third function, and sometimes it means passing in enough information that I can do it all in once function.

Refactoring takes a lot of discipline, but it’s a given that at some point someone will be looking through it wondering what in the heck this piece of code does. It’s an easy enough concept, but sometimes I find myself in a pile of code written by who-even-knows that I can’t understand. These are the moments where I find it’s useful to go back to refactoring basics and chip away at it to build my own understanding, and improve the code in the future.

If you want to dive in more, here are a few other Spin posts I’d recommend:

What techniques do you use to refactor?