Refactoring vs Rewriting - Decide What Should Be Done

According to Stack Overflow's 2024 Developer Survey, the amount of technical debt is the top frustration for software developers in their work, with over 62% of developers feeling its impact. In the survey, almost all professional developers agree that improving quality of code provides the most satisfaction at work. To navigate these challenges, mastering code improvement techniques is key: Refactorings and rewrites require the right technical skills, strategy and the buy in from management. This blog series will explore the key aspects every developer should know, offering practical tips and tricks for improvement.

1. Refactoring vs Rewriting Part 1: Knowing The Basics
2. Refactoring vs Rewriting Part 2: Building The Strategy
3. Refactoring vs Rewriting Part 3: Convincing The Boss

In the first post of the "Refactoring vs. Rewriting" series, we discussed the technical essentials every developer needs for tackling these tasks. Understanding good coding principles and how to apply them is crucial for both refactoring and rewriting code.

But is technical expertise enough? Can we simply refactor here and there, and opt for a rewrite if it "makes sense"? There is some truth to this, especially if you follow the Boy Scout Rule, which translates into tech like:

"Every time you work on code, leave it a little cleaner than you found it."

While this is a great practice for any software engineer, dealing with larger codebases spanning multiple files, domains, or systems requires a different approach. Today, we'll explore how to decide when refactoring is necessary and feasible, considering not only coding skills but also the human dynamics within your team.

Refactoring done wrong

I remember a situation in my earlier jobs. Just after reading the book about "Clean Code" by Robert C. Martin, I was very enthusiastic about cleaning up some larger codebase I was working with. All the ideas from the book I could try out and apply in code. So many pieces of the code I was working on were not following any of the guidelines that you learn in his book.

I went ahead and started right away, equipped with all the tools and newly learnt knowledge, but no experience :-). There were no tests in place to validate that all business critical features are running fine, but I thought it would be okay, since I knew most of the workflows anyway. Manual testing afterwards will do.
It started small, little changes here and there, some renames of files, method names optimized and so on. Great! Good job! Good job? Well, not really.
These changes were taking up more and more time, and of course I went down the rabbit hole: You change one thing, you have to change 3 other things. More and more files changed, all on the main branch. Almost there, just a little more. And then deploy!

Then came the day of reckoning. A critical bug was reported. And another one… My changes had spiraled out of control, and the codebase was in chaos. As we tried to pinpoint the issue, it became clear that my well-intentioned efforts had introduced several new problems. The bugs in the system were numerous and elusive.

The team gathered around, trying to backtrack and fix the mess. Hours turned into days, and the deadlines for new features were missed. We couldn't deploy any new features for days, and frustration grew. The impact was severe: the development of new features was delayed, our deployment pipeline was clogged, and confidence in our team's ability to deliver took a significant hit.

In the end, we managed to get things back on track, but the lesson was invaluable. From that day forward, I approached refactoring with more caution: Rather smaller refactoring steps are better than the big rewrite. Write tests before making any changes, and communicating more with my team about the changes made. The experience taught me that clean code isn't just about aesthetics or following guidelines; it's about maintaining stability, reliability, and ensuring that changes don't disrupt the system and workflows. Clean code is a continuous process that requires patience, collaboration, and, most importantly, respect for the codebase and the people who depend on it.

Don't get into such a situation! Here are some general tips on how to decide if a code rewrite or refactor is necessary and which common pitfalls.

When to Refactor and When to Rewrite

To determine whether to refactor or rewrite code, consider the quality of your current codebase and business logic. Assess and measure these aspects before proceeding. Use this framework to guide your decision:

• Good Code, Good Business Logic: No changes needed. Avoid refactoring just for the sake of it, and definitely don't consider a rewrite.
• Poor Code, Good Business Logic: Refactor. Clean up the code without altering its functionality.
• Good Code, Poor Business Logic: Refactor the business logic while maintaining the technical foundation.
• Poor Code, Poor Business Logic: Rewrite. Start fresh with new requirements.

Then, before you jump into refactoring, be aware of potential hurdles:

Common Pitfalls and How to Avoid Them

Starting a refactoring or rewriting journey is challenging. Here are the top five reasons these projects often fail, and how to avoid them:

1. Underestimating Complexity: Existing code often contains hidden knowledge and solutions to obscure problems. Understand the current system thoroughly before making changes.
2. "Silver Bullet" Syndrome: New technologies or frameworks are not cure-alls. They bring their own challenges. Ensure your team is proficient with the new tech before making a switch.
3. Assuming Perfect Execution: No project goes perfectly. Plan for setbacks and be prepared to encounter similar issues as those in the original code.
4. Undervaluing Existing Code: Even messy code has value. It represents countless hours of problem-solving and adaptation. Don't discard it lightly.
5. Lack of Commitment: Both refactoring and rewriting are long, arduous processes. Ensure your team is ready to stay the course, maintaining morale and motivation.

Essential Strategies for Success

Before diving into a refactoring or rewriting project, consider these strategies:

• Complete Test Coverage: Ensure your business logic is fully covered by tests. This is non-negotiable for successful refactoring.
• Manage Technical Debt: Avoid refactoring if your technical debt exceeds 40%. Focus on addressing the root causes of your current problems.
• Branching Strategy: Implement changes in separate branches to avoid duplicating efforts. Plan for how new features will be integrated during the refactoring process.
• Team Skills: Ensure your team is skilled in design patterns, clean code practices, and the chosen technologies. Consistency in coding standards is key.
• Documentation and Feature Re-evaluation: Document all features of the current application. Ensure no valuable functionality is lost in the transition.

Conclusion: Preparation is Key, But There's More to Know

Refactoring and rewriting are not just technical decisions—they are strategic ones that require careful planning and execution. As a software developer, you need to be armed with knowledge on how to write good code and measure its quality, which we covered in the first part of this blog series.

Don't underestimate the work ahead. Be aware of common pitfalls and mistakes when deciding on a code overhaul. Set up a strategy for delivering quality code and be prepared for setbacks.

But before you start, consider another aspect: Remember that software is often written for a purpose—a company or a project. How do YOU justify the need for refactoring to management? Best practices alone won't convince decision-makers. In our next blog post, we'll discuss the business factors that play into the decision-making process for leaders to decide or decline a refactoring or rewrite. Check it out here!

Utterskills - We are an e-learning academy for IT-professionals and provide micro learning video courses for all relevant topics beyond code in IT-careers. Did you like this article? Then you're gonna love our videos! Why don't you give it a try? It's free!