A guide to refactoring

I’d be a millionaire if I had a dime for every time I heard someone say, “We need to refactor the code before implementing this feature.” However, sometimes I struggled to understand why refactoring was so important and how to deal with it.

Despite having a technical background, refactoring troubled me because:

• The developers said it would take two days, and then it took two weeks
• We refactored a piece of code and broke something unrelated to it
• Management continuously challenged why we had to do it
• Intense debates circulated between refactoring and adding product capabilities

Have you ever stumbled upon this yourself?

Keep reading to learn more about what refactoring is, why it matters, when you should refactor, and techniques you can use to implement it within your product team.

What is refactoring and why does it matter?

If you work with digital products, you probably hear the term refactoring.

Refactoring involves improving the quality of the code base while preserving its current functionalities. This creates a more maintainable, scalable, and robust code.

You may wonder why software engineers don’t just build the code base right from the beginning. In general, development teams take one of two approaches:

1. Build it right from day one — Getting your product into your customers’ hands takes a while. In the process, you may learn it’s not what they need, forcing you to adapt or throw it away. This approach requires a lot of upfront investment and can lead to waste
2. Build to learn, then to scale — Prioritize learning over code quality, so you understand whether customers actually want to use your solution. If your product ends up a bust, you can drop it without too much investment. If your product does well, you can refactor and scale

From my experience, software engineers push for the first, while product managers push for the second. To help you decide, ask the following questions:

• How confident are you that customers want the feature?
• What evidence do you have that customers will understand how to use it?
• How do you know the business value you’ll collect from it?

The more confident you are, the more you can build from the beginning. Sadly, that’s seldom the case. More often than not, you’ll need to refactor code.

Real-world examples of refactoring

To help you better understand refactoring, I have an example of a failed and a successful attempt.

Failed refactoring

I worked for a digital marketplace, and customers complained that uploading new products took too long. The reason was simple:

• Our image-processing algorithm was outdated
• As the volume increased, processing pictures would take hours instead of seconds
• Our shop didn’t present products without images

The problem was critical, and we had to act.

A senior software engineer asked me to let him refactor the code during the rest of the week. I agreed with him. As the week finished, he was confident that we could put it live. We set the following Monday as our release date.

The refactoring went live on Monday at 7am, and the image processing time became 150 times faster. That was awesome. I couldn’t believe it. We were so happy I invited the software engineer for a delicious breakfast.

The marketplace director awaited us when we returned to the office at 08:37. His face was anything but friendly as he said, “David, fix whatever you guys did. We’re missing 50K products in our shop.”

That was it. An unexpected effect of refactoring occurred. It caused a conflict with the shop importer, resulting in the removal of products from our catalog. Why did we get there?

• Refactoring without having automated end-to-end tests
• Low test coverage
• Focus on making the code better without looking at the big picture

It was painful, but it taught me a lot.

Successful refactoring

Another time, at the end of the month, we issued invoices to all partners. We had to change a few details to make it more transparent. When I brought this to the team, my software engineers said they wouldn’t do it without refactoring. The reason was simple: the code was complex, unscalable, and outdated.

I agreed with them on refactoring. To ensure success the tech lead:

• Confirmed the tests were implemented
• Understood the code in-depth before touching it
• Searched for dependencies and evaluated the impact

The team needed a whole week to refactor it. By the end of it, we learned:

• 95 percent of tests passed, but a few scenarios still failed
• All dependencies remained working as expected
• The code was reduced from 9000 lines to 6000

After evaluating the results, we invested another day to cover the remaining edge cases. That resulted in simpler and more maintainable code, which allowed us to add changes in a few days instead of weeks.

When to refactor

Knowing when to refactor is as crucial as doing the refactoring itself. Good refactoring leads to:

• The same functionalities working as well as before
• Simplified code base
• More maintainable application
• No side effects with other parts of the product

Before you start refactoring you need to make sure you have:

• Good test coverage
• Code understanding
• Clarity on dependencies
• Understanding on functionalities

But when should you refactor? When you observe the following, it’s time to consider a refactor:

• Consistent audience growth
• Complaints from software engineers about the complexity of the code
• Increased code smell warnings
• Onboarding new members takes considerable effort
• Frequent problems whenever the code evolves

Refactoring techniques

Once you decide to refactor, you can benefit from a few techniques:

1. Extract methods — Some methods may become too long and hard to understand. Creating multiple shorter methods will increase readability and reusability
2. Extract class — As the above shows, classes can become extremely long and hard to understand; making them shorter improves code readability and reusability
3. Renaming — Readability is fundamental to helping software engineers evolve the code frictionlessly. Yet, it’s inevitable that classes, methods, and variables receive unclear names. Replace them with clear names and follow a standard naming convention
4. Use constants instead of magic numbers — Sometimes, the code receives numbers for conditionals. For example, “If score > 7; pass = 1.” What does 7 mean here? It’s better to define a constant (e.g., “PASS_SCORE = 7”). This improves readability and reduces bugs
5. Simplify conditionals — The more complex your conditionals become, the more trouble you may have. It’s better to simplify them so anyone can quickly grasp what’s expected
6. Remove unused code — Eventually, you won’t use some of your code. In these cases, remove the unnecessary parts
7. Shift methods — Sometimes, methods can make your readability difficult. Shift them to make for easier reading

Refactoring vs. rewriting

When you choose to refactor your code, it’s still usable, up-to-date, and relevant, but you need to make it simple to understand and more maintainable. Yet, sometimes, refactoring wouldn’t be the best choice. Reflect on the following:

• What’s faster, refactoring or rewriting the code?
• Is the programming language used still relevant, or did it become outdated?
• Does everyone understand your code, or only the person who wrote it?

The more your answers skew to the right, the more you’d benefit from rewriting the code.

Rewriting means throwing away the current code version because it’s no longer maintainable or scalable. It implies redoing everything the previous code provided in a new way. However, consider this approach a last resort because it’s time-consuming and brings risks of unexpected side effects.

Final thoughts

Code rarely starts perfect, so it needs to evolve according to the value it creates for your customers and business. When the time arrives, refactoring helps you keep your code base simple, scalable, and maintainable.

That said, refactoring requires preparation to avoid undesired side effects. You might consider rewriting as an alternative, if refactoring requires more work than writing the code from scratch. Remember, always maintain an open dialog about when to refactor and when not to.

Featured image source: IconScout