Refactoring is a daily practice for developers, but it’s often viewed as complex. According to stats from my last project, bad refactoring ranked 6th among the top causes for introducing bugs. However, avoiding refactoring isn’t the solution—it's an essential process for maintaining the quality and scalability of a software project. Over time, technical debt builds up, slowing down development, demotivating stakeholders, impacting product stability, and making it harder to scale. Refactoring is a must-have tool to not only prevent the growth of debt but also reduce it in more extreme cases.

I recently attended the Mobilis in Mobile conference and took a course on this topic. I'd like to share the key points about refactoring and how to master it. In this final article of the series on refactoring, I’ll outline a few techniques to convince your team that refactoring is not a luxury, but a necessity. Let’s be honest, it’s not always easy to make them understand why it’s important to invest time and resources into it. Usually, when a decision-maker isn’t convinced, one of two things happens: either the developer postpones the work, or they secretly refactor without the client’s explicit approval.

But working behind the scenes or endlessly delaying refactoring is rarely a good strategy. So how do you convince your team that this work is not only helpful but critical to the project’s success? Here are a few ways to make your argument.

Rule #1: Speak to Their Needs, Not Yours

If you’re speaking with a CTO, you might want to emphasize the product’s quality. But if you’re dealing with a project manager or a marketing lead, you’ll need to focus more on users or return on investment (ROI). Your message needs to be tailored to your audience, which means you must understand the interests of the person you’re speaking to. The Client Value Model can help structure your approach by focusing on what matters most to the decision-maker. In a product company, your "client" might be the executive team or the CEO. In a service company, it’s often an external client.

The Client Value Model

This framework focuses on identifying the decision-maker’s priorities (time to market, total cost, user satisfaction, etc.) and understanding what frustrates them (being excluded from user interviews, not being involved in deciding future features, etc.). The idea is to adjust your message accordingly. This means framing refactoring as a direct solution to your audience’s objectives. For example, if their main concern is the speed of delivering new features, explain how refactoring can help accelerate future development.

When a car dealer wants to sell you a car, he analyzes your specific needs. If you're looking for a reliable vehicle because you’re tired of frequent repairs, he’ll steer you toward a Toyota, highlighting the brand’s exceptional defect management, making it one of the most reliable. For another customer who prioritizes cutting-edge design, the dealer will emphasize Toyota’s design center in southern France.

Rule #2: Ditch the Jargon, Speak in Results

Keep It Simple—Don’t Lose Them in the Details

When it comes to convincing a decision-maker, avoiding technical jargon is key. Talking about "cyclomatic complexity" or "design patterns" often clouds the message. What the client understands are gains, consequences, risks, and costs. Speak to them in terms of money or time spent—those are concepts they grasp easily.

If you ask your mechanic why you need to change a filter or check the brakes, they won’t dive into details about hydraulic pressure in the cylinders. Instead, they’ll simply say: "If you don’t, your car might break down on the highway, and you'll end up paying much more." Use the same approach.

Show Them the Wins: Why Refactoring Pays Off

Explain how refactoring is beneficial for the project: improved stability, fewer bugs, increased user satisfaction. These tangible gains resonate with decision-makers. For example, you could point out that addressing the issue now will prevent having to come back in a few months to fix a much more expensive problem—just like replacing a filter in a car prevents future breakdowns.

Highlight the Hidden Costs of Doing Nothing

On the flip side, it's equally important to highlight the cost of action and the risk of inaction. What are the consequences if refactoring isn’t done? More bugs, longer fixes, or even production crashes.

Imagine your mechanic telling you that ignoring a repair now increases the risk of a breakdown by 10%, with a much higher repair cost later on. Refactoring works the same way: by delaying these improvements, the future costs increase exponentially.

Rule #3: Let the Numbers Do the Talking

Just like you estimate the cost of developing new features, you can also estimate the cost of refactoring. Simply compare the time required to add a new feature with and without refactoring.

While the development time argument is often straightforward for developers, it’s not the only metric for cost. You’ll also need strong arguments for the benefits. Let’s explore a few key performance indicators (KPIs) that will be your allies in convincing your team.

Track What Matters: Key Metrics for Refactoring Success

A decline in a KPI over time can indicate a need for refactoring, while tracking an increase can show the success of a refactoring. It’s important to narrow the scope of these metrics to the specific area of the project in question. Here are a few indicators that follow this rule:

• Test coverage
• CI build success rate
• Developer velocity
• Delivery frequency
• User satisfaction score
• Developer satisfaction score
• Number of new features

And conversely, here are the KPIs where an increase demonstrates a problem:

• Number of bugs
• Number of users affected by major bugs
• Time to fix bugs
• Number of production crashes
• Number of linter warnings

These KPIs will help you highlight the rising costs of inaction and the benefits of refactoring. You can also present additional arguments, such as the risk of regression, the fact that no other developments are ready, team turnover, and more.

Use visual graphs. Sometimes, a simple diagram showing the rise in bugs for a key feature can be more persuasive than a long explanation.

Ideally, in line with rule #2 about speaking a common language, you should be able to convert these metrics into money, representing the financial loss for the client. For this, you’ll find plenty of real-world examples in the book The Economics of Software Quality.

Rule #4: Handle the Small Stuff Now, Avoid Big Headaches Later

Imagine a mechanic. When you take your car in for a service, he doesn’t ask if you want him to check for oil leaks—it’s obvious to him, he does it as a matter of safety and performance. As a developer, you should adopt the same mindset: if a refactor is quick and immediately improves the quality of the code, just do it without initiating a lengthy negotiation. This aligns with the Boy Scout Rule: always leave the code cleaner than you found it.

Wrap It Up: Make Refactoring a Non-Negotiable

Convincing a client to invest time in refactoring requires preparation, clear arguments, and an understanding of your audience’s priorities. Don’t get lost in unnecessary technical details. Explain the benefits of refactoring, contrast the cost of refactoring with the cost of inaction, and suggest metrics to track the success of the refactor. Present your arguments verbally with visual graphs. And remember: just like a mechanic doesn’t ask if you want them to check the basics of your car, some refactors should be done without discussion.

The more you succeed in gaining approval for meaningful refactoring efforts, the easier it will be to convince stakeholders for future investments—especially with all the tracking metrics you’ll have in place.

Previous articles

Part 1: Technical debt

Part 2: The developer's manual

‍