And managers frequently view refactoring as "not a business need" until it boils over and becomes the most significant business need possible.

"Oh, our software somehow works. We can't implement any new changes. And oh, everyone is quitting because work is miserable."

In this article, I’ll walk you through the steps I use to refactor a complex codebase. We’ll talk about setting goals, writing tests, breaking up monoliths into smaller modules, verifying changes, making sure existing features still work, and keeping tabs on performance. I’ll also show you how to speed up reviews using AI tools.

By following these steps, you can turn complex, fragile code into a clean, reliable codebase your team can own.

The Issue of Technical Debt

As projects grow and evolve, technical debt increases. Code that was once functional and manageable turns into an unmaintainable mess, where even small changes become risky and time-consuming.

Despite the obvious need for cleanup, refactoring rarely gets prioritized because there's always something more urgent, new features, bug fixes, and client demands.

I’ve had conversations with engineers, many of whom are working on enterprise software and are fully aware of their codebase's code smells and inconsistencies. They dislike the situation but feel powerless to change it.

So how do we shift from a culture of writing for pure functionality to a culture that values maintainability, especially for complex codebases?

It’s usually a mistake to completely halt new feature development for a long refactoring period (except perhaps in emergencies). Business needs still exist, and putting everything on hold can create tension and lost opportunities. It’s better to find a balance so you’re still delivering value to users even as you clean under the hood.

While there is no one-size-fits-all solution, a structured approach can help teams introduce sustainable refactoring practices, even in environments where management is resistant. Let’s explore how this works.

Table of Contents:

• What is Refactoring?

• Preparing for Refactoring

  • Secure Management Buy-in

  • Ensure a Safety Net with Automated Testing

  • Identify High-Risk Areas

  • Set Clear Refactoring Goals

• Techniques for Refactoring Complex Codebases

  • 1. Identifying and Isolating Problem Areas

  • 2. Incremental vs. Big Bang Refactoring

  • 3. Breaking Down Monolithic Code

  • 4. Ensuring Backward Compatibility

  • 5. Handling Dependencies and Tight Coupling

  • 6. Testing Strategies (Safely Refactoring with Confidence)

  • 7. Refactoring Without Breaking Performance

  • 8. Automate Code Reviews with AI Tools

  • Summary

What is Refactoring?

Many people all too often use the word "refactor" when they mean a targeted rewrite.

As Martin Fowler famously said,

“Refactoring is a controlled technique for improving the design of an existing code base. Its essence is applying a series of small behavior-preserving transformations... However, the cumulative effect... is quite significant.”​

In practice, this means continuously polishing code to reduce complexity and technical debt.

While traditional software development follows a linear approach of designing first and coding second, real-world projects often evolve in ways that lead to structural decay. Refactoring counteracts this by continuously refining the codebase, transforming disorganized or inefficient implementations into well-structured, maintainable solutions.

A targeted rewrite is a focused overhaul of a specific aspect of an application, often affecting multiple parts of the codebase. It carries more risk than refactoring but is still controlled and contained.

Preparing for Refactoring

Even the most skilled refactoring effort can stall without proper preparation. Before you start moving code around, laying a foundation that will keep your work organized and your team on the same page is crucial.

Here are some steps you can take to ensure your refactoring efforts are successful.

Secure Management Buy-in

As I’ve already discussed, getting time for refactoring can be difficult in feature-driven organizations. Often, management will accept refactoring investment if you can tie it to business outcomes, faster time to market, fewer outages (which translates to happier customers), and the ability to take on new initiatives.

Make those connections explicit. For example, you could say:

“If we refactor our reporting engine now, it will make it feasible to add the analytics module next quarter, which unlocks a new revenue stream.”

Or use data:

“We spent 30% of our last sprint fixing bugs in module Y. After refactoring Y, we expect that to drop significantly, freeing time for new features.”

Business-minded arguments help justify the balance.

Ensure a Safety Net with Automated Testing

As you refactor, tests are your safety net. Before modifying a component, write characterization tests around it if they don’t exist.

# example: characterization test for a legacy function
def legacy_calculate_discount(price, rate):
    # ... complex logic you don't fully understand yet ...
    return price * (1 - rate/100) if rate < 100 else 0

def test_legacy_calculate_discount():
    # capture existing behavior
    assert legacy_calculate_discount(100, 10) == 90
    assert legacy_calculate_discount(50, 200) == 0

These tests capture the current behavior, so you’ll know if you accidentally change it. Unit tests, integration tests, and e2e tests all validate that refactoring hasn’t broken anything.

It’s often worth investing time in setting up a continuous integration pipeline so that every change triggers automated tests. This gives rapid feedback and confidence that you’re not introducing regressions. Robust testing and CI/CD enable you to move faster and refactor with peace of mind.

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with: python-version: '3.10'
      - run: pip install -r requirements.txt
      - run: pytest --maxfail=1 --disable-warnings -q

Identify High-Risk Areas

The first step is to figure out what to refactor. High-risk areas are parts of the code likely to cause bugs or slow development. Common signs include long methods, large classes, duplicate code, and complex conditional logic​.

Such code “smells” often hint at deeper design problems. Tools like static analysis can automatically flag these issues.

For example, SonarQube will mark code smells (like high complexity or long methods) that increase technical debt​. Using SonarQube or similar tools, you can generate reports on code complexity (for example, cyclomatic complexity metrics​) and find hotspots in the codebase that need more attention.

Set Clear Refactoring Goals

Before refactoring code, define the goal.

Goals must be specific and measurable. For example, you might aim to reduce a class’s size or a function’s cyclomatic complexity by a certain amount or to increase unit test coverage from 60% to 90%.

Each goal is tied to a measurable outcome: shorter methods, fewer if statements or classes with a single responsibility, faster execution for processing orders, higher test coverage, and no unused code. These targets will guide our refactoring plan and let us verify when we’ve succeeded.

Tip: Write down your refactoring goals and share them with your team. This sets expectations that you’re not adding new features in this effort, just making the code cleaner and more robust. It also helps justify the time spent by showing the benefits (like more straightforward future additions and fewer bugs).

Techniques for Refactoring Complex Codebases

1. Identifying and Isolating Problem Areas

It can be overwhelming to decide where to start refactoring a large codebase. Not every part of the code needs refactoring – some areas are delicate or rarely touched.

The most impactful refactoring efforts typically target the “problem areas”: parts of the codebase that are overly complex, error-prone, or act as bottlenecks for development and performance. Identifying these areas is a crucial first step.

Techniques for Finding Hotspots

Team knowledge & developer frustration

Don’t underestimate the value of anecdotal information from the team. Which parts of the code do developers dread working in? Often, the team’s instincts point to areas that are hard to understand or modify (for example, “the accounting module is a black box, we hate touching it”). These could be areas to improve.

In my experience, simply asking, “If you had a magic wand, which part of the code would you rewrite?” yields very insightful answers.

Code complexity metrics

Use static analysis tools to measure cyclomatic complexity, code duplication, large functions/classes, and so on. Files or modules with extremely high complexity numbers or thousands of lines are good candidates for scrutiny. But static complexity alone doesn’t tell the whole story – a file might be ugly but rarely touched.

Change frequency (Churn)

Look at version control history to see which files are often changed, especially those associated with bug fixes or incidents.

Hotspot analysis

A robust approach combines complexity and change frequency to find “hotspots.” For example, a tool or technique plotting modules by their complexity and how often they change can highlight the problematic areas. CodeScene (a code analysis tool) popularized this: hotspots are parts of the code that are highly complex and frequently modified, indicating areas where “paying down debt has a real impact”​.

If a module is a mess and developers are in it every week, improving that module will likely yield outsized benefits (fewer bugs, faster adds).

Performance bottlenecks and crashes

Some parts of the codebase become targets for refactoring because they cause frequent performance problems or outages. For instance, if a specific service or job crashes often or can’t keep up with the load, you might need to refactor it for stability.

How to Isolate Problem Areas

Once you’ve identified a hotspot or problem area, the next challenge is isolating it so you can refactor safely. In a complex system, nothing lives in complete isolation. That problematic module likely interacts with many others.

Here are strategies to isolate and tackle it:

Break dependencies (Create seams)

Michael Feathers (in Working Effectively with Legacy Code) introduced the concept of “seams” – places where you can cut into a codebase to isolate a part for testing or refactoring. This might mean introducing an interface or abstraction between components so you can work on one side independently.

For example, suppose PaymentService is tightly coupled to StripeGateway, with direct calls scattered throughout the code.

# payment_service.py

def charge_customer(order_id, amount):
    # Hardcoded dependency to Stripe
    stripe = StripeGateway()
    stripe.charge(order_id, amount)

To isolate and refactor the payment logic safely, you can introduce a PaymentProcessor interface and have PaymentService depend on that interface instead. Then, create an adapter like StripeAdapter that implements PaymentProcessor and delegates to the existing Stripe logic.

This way, you can safely refactor or even replace the Stripe integration behind the StripeAdapter without impacting PaymentService or any other module that uses it. As long as the PaymentProcessor interface is honored, the rest of the system remains unaffected.

# interfaces.py

class PaymentProcessor:
    def charge(self, order_id, amount):
        raise NotImplementedError


# stripe_adapter.py

class StripeAdapter(PaymentProcessor):
    def charge(self, order_id, amount):
        # Internally still uses Stripe
        stripe = StripeGateway()
        stripe.charge(order_id, amount)


# payment_service.py (Refactored)

class PaymentService:
    def __init__(self, processor: PaymentProcessor):
        self.processor = processor

    def charge_customer(self, order_id, amount):
        self.processor.charge(order_id, amount)

“Branch-by-abstraction”

This technique is related to the above and is often used in continuous delivery. The idea is to add a layer of abstraction (like an interface or proxy) in front of the old code, have both old and new code implementations behind it, and then gradually shift usage from the old to the new implementation. For a while, you might have a temporary state where both versions exist (perhaps toggled by a config or feature flag).

This is similar to how the strangler fig pattern works at an architectural level. It’s a bit of extra work (since you maintain two paths for a while), but it allows you to migrate functionality and fall back if needed incrementally.

Aim to identify the 20% of the code causing 80% of the problems. Focus your refactoring energy there for maximum impact. When you do, create a plan to isolate that area via abstractions, interfaces, modules, or other means so that you can work on it with minimal risk of side effects. The more you can contain the blast radius of a refactoring, the more confidently you can move forward.

2. Incremental vs. Big Bang Refactoring

One of the first strategic decisions is approaching the refactor incrementally or going for a “big bang” overhaul. In most cases, an incremental approach is preferable, but there are scenarios where more significant coordinated refactoring steps are considered.

Let’s break down what these mean:

# before: one large function with multiple responsibilities
def process_order(order):
    validate(order)
    apply_discount(order)
    save_to_db(order)
    send_confirmation(order)
    log_metrics(order)
    update_loyalty_points(order)
    # potentially more steps 

# after: refactored incrementally into clearer, smaller units
def process_order(order):
    validate(order)
    apply_discount(order)
    persist_and_notify(order)

def persist_and_notify(order):
    save_to_db(order)
    send_confirmation(order)
    log_metrics(order)
    update_loyalty_points(order)

Incremental refactoring

This means making small, manageable changes over time rather than attempting a massive overhaul in one shot. The system should remain functional at each step (even internally in transition). The advantage is risk mitigation: each small change is less likely to go wrong, and it’s easier to pinpoint and fix if it does.

Incremental delivery lets you confirm changes in production and makes diagnosing issues easier since you’re only changing one small thing at a time​. It also means the system keeps running during the refactor, so there’s less pressure to rush to “get the system back to working condition”​. If priorities shift, you can pause after some increments and still have a working product.

Big bang refactoring (Rewrite)

This is the “tear it down and rebuild” approach. You stop adding new features, possibly freeze the code for a period, and devote a considerable effort to redesigning or rewriting a significant portion (or the entirety) of the system. The idea is to emerge on the other side with a brand new, clean system.

So when (if ever) is a big bang justified? Perhaps when the existing system is truly untenable – for example, an outdated technology that must be replaced (such as a platform that can’t meet new performance or security requirements or code written in a language no longer supported). Even then, wise teams often simulate a big bang by breaking it into stages or developing the new system in parallel.

Whenever possible, favor an incremental refactoring strategy. Teams successfully pull off massive transformations by treating the big refactor as a series of mini-refactors under a shared vision.

3. Breaking Down Monolithic Code

Many complex codebases start life as a single monolithic application, one deployable, a single code project, or a tightly coupled set of modules all maintained and released together.

Over time, monoliths can become unwieldy, builds take forever, a change in one area can unintentionally affect another, and teams can be complex to scale because everyone is stepping on each other’s toes in the same code. A common refactoring challenge for senior engineers is modularising or splitting a monolith into more manageable pieces.

# define the interface
class PaymentProcessor:
    def charge(self, amount): ...

# old implementation
class LegacyProcessor(PaymentProcessor):
    def charge(self, amount):
        # original code

# new implementation behind a feature flag
class NewProcessor(PaymentProcessor):
    def charge(self, amount):
        # cleaner code

def get_processor():
    if config.feature_new_payment:
        return NewProcessor()
    return LegacyProcessor()

# usage remains the same
processor = get_processor()
processor.charge(100)

Strategies for modularization.

• Layer separation: Start by enforcing logical layer boundaries. For example, separate the user interface code from business logic and separate business logic from data access. In a messy monolith, these concerns often get mixed together. By organizing the code into layers (even within the same repository), you can limit the ripple effect of changes.

• Domain-based modularization: If your system spans multiple business domains or functional areas, consider splitting along those lines. For example, an e-commerce monolith might be separated into modules like Accounts, Orders, Products, Shipping, and so on.
  Each could become a subsystem or a package. The goal is to minimize the information these modules need to know about each other’s internals (high cohesion within modules and clear APIs between them).

• Microservices or services extraction: In recent years, the trend has been to break monoliths into microservices, independent services that communicate over APIs. This form of architectural refactoring can significantly improve independent deployability and scalability. But it’s a significant undertaking with complexities (distributed systems, network calls, and so on). If you decide to go this route, do it gradually.
  A proven method is the strangler fig pattern mentioned earlier: you pick one piece of functionality and rewrite or extract it as a separate service, redirect traffic or calls to the new service. At the same time, the rest of the monolith remains intact and iteratively does this for other pieces​.

• Modular monolith: Not every system needs to go full microservices. There’s an approach called a modular monolith, essentially structuring your single application into well-defined modules that communicate via explicit interfaces (almost like internal microservices but without the overhead of separate deployments).

This can give you many microservices' advantages (clear boundaries, separate development responsibility) while avoiding operational complexity.

• Identify shared utilities vs. truly independent components: In breaking down a monolith, some code is widely shared (like utility functions or cross-cutting concerns such as authentication). It might make sense to factor those into libraries or services first, as they will be needed by whatever other pieces you split out.

While breaking down a monolith, maintaining functionality during the transition is essential. Techniques like backward compatibility (discussed next) and thorough testing will be your safety net.

Finally, be prepared for the team workflow to change. If you move to microservices, teams might take ownership of different services, requiring more DevOps and communication across teams. If you keep a modular monolith, enforce code ownership or review rules to keep the modules from tangling up again (for example, you might restrict direct database access from one module to another’s tables, and so on).

4. Ensuring Backward Compatibility

A critical concern during large refactoring is: Will our changes break existing contracts?

In other words, can other systems, modules, or clients that rely on our code work as expected after we refactor? Backward compatibility is especially important if your codebase provides public APIs (to external customers or other teams), data persisted in a certain format, configuration files that users have written, etc.

Here are some strategies and considerations to maintain backward compatibility:

Suppose you have a widely-used function like send_email(to, subject, body). You want to refactor the internal logic to support additional features like HTML formatting, but you don’t want to break existing callers.

Instead of changing the function signature, you keep the public API unchanged and delegate to a new internal function:

# original API
def send_email(to, subject, body):
    # send mail...

# refactored internals, keep signature
def send_email(to, subject, body):
    sendv2(to=to, subject=subject, body=body)

def sendv2(to, subject, body, html=True):
    # new implementation with HTML support

The internal send_email_v2() function adds new capabilities like HTML formatting, but older code using send_email() still works without any modifications.

If you're introducing a new, improved version like send_email_v2(to, subject, body, html=True), it's good practice to:

• Mark the old version (send_email) as deprecated in documentation.

• Ensure the old version internally calls the new one.

• Give other teams time to migrate at their own pace.

Use versioning for external APIs

If your system provides an HTTP API or similar to external clients, the safest route for major changes is to version the API. Introduce a v2 API endpoint for the refactored logic, keep v1 running (maybe internally calling v2 or using a translation layer). Clients can move to v2 at their own pace.

It’s extra work to maintain two APIs temporarily, but it prevents a breaking change from angering users or causing outages. Always communicate changes clearly and provide migration guides if applicable.

Have a clear deprecation policy

Make sure there’s a policy (and communication) around how long deprecated features will be supported. For internal APIs, maybe it’s one release cycle. For external ones, maybe multiple cycles or never removal without a major version bump. A good practice is to announce deprecation early.

If you’re exposing an HTTP API, consider introducing a new versioned endpoint (for example, /api/v2/send_email) and maintain the older /api/v1/send_email temporarily. Internally, v1 might call v2 with default parameters, ensuring behavior stays consistent for existing clients.

In summary, maintain backward compatibility whenever possible, and implement a clear deprecation policy for anything you do change​.

Write adapter or compatibility layers

In some cases, you can write an adapter to bridge old and new systems. For instance, suppose you refactor the underlying data model of your application, but you still have old configuration files in the old format. Rather than forcing all those files to be rewritten immediately, you could write a small adapter that translates the old format to the new one at runtime (or during startup). This way, old data continues to work.

Test for compatibility

Include tests that specifically ensure backward compatibility. For instance, if you have a public API, keep a suite of tests using the old API contracts and run them against the refactored code, they should still pass.

In summary, ensure that as you refactor, the external behavior and contracts remain consistent. This careful approach protects your users and downstream systems, allowing you to reap the internal benefits of refactoring without causing external chaos.

5. Handling dependencies and tight coupling

One of the hairiest aspects of refactoring a large codebase is dealing with deeply interdependent code. Complex systems often suffer from tight coupling. Module A assumes details about Module B and vice versa, global variables or singletons are used all over, or a change in one place ripples through half the codebase.

Reducing coupling is a significant aim of refactoring because it makes the code more modular, meaning each piece can be understood, tested, and changed independently. So, how do we gradually loosen the coupling in a legacy system?

Let’s go over some strategies to reduce coupling.

Introduce interfaces or abstraction layers

A very effective way to decouple is to put an interface between components. For example, if you have a class that directly queries a database, introduce an interface and have the class use that instead. The underlying database code implements the interface.

# before: direct instantiation
class OrderService:
    def __init__(self):
        self.repo = OrderRepository()

# after: inject dependency
class OrderService:
    def __init__(self, repo):
        self.repo = repo

# wiring up in application startup
repo = OrderRepository(db_conn)
service = OrderService(repo)

Now, that class no longer depends on how the data is fetched. Applying the dependency inversion principle depends on abstractions, not concretions.

Use dependency injection

Once you have interfaces, use dependency injection to supply concrete implementations. Many frameworks support DI containers, or you can do it manually (passing in dependencies via constructors). Dependency injection means code A doesn’t instantiate code B itself – instead, B is passed into A.

This approach also makes unit testing easier (you can inject mock dependencies).

Facades or wrapper services

If a particular subsystem is heavily entangled with others, consider creating a Facade, an object that provides a simplified interface to a larger body of code. Other parts of the system are then called the Facade, not the many internal methods of the subsystem. Internally, the subsystem can be refactored (even split into smaller pieces) as long as the Facade’s outward interface remains consistent.

This is similar to how microservices work (other services don’t care how one service is implemented internally – they just call its API), but you can do it in-process, too.

Gradual replacement (Parallel Run)

If a specific component is to be replaced with a new implementation, it can help to run them in parallel for a while. For instance, if you have a spaghetti module that you want to redo correctly, you could leave the spaghetti code in place for legacy calls but start routing new calls to the new module.

The result is a codebase where changes in one area (hopefully) won’t unpredictably break another, a key property of a maintainable system.

6. Testing Strategies (Safely Refactoring with Confidence)

A robust testing strategy will give you the confidence to make sweeping changes because you’ll know quickly if something important breaks. Here’s how to approach testing in the context of a large refactoring:

Establish a baseline with regression tests

Before you even begin refactoring a particular component, make sure you have tests that cover its current behavior. You're lucky if the codebase already has a good test suite, but many legacy systems have inadequate tests.

One of the first tasks in those cases is often writing characterization tests. A characterization test is a test that documents what the system currently does, not what we think it should do​.

As Feathers says, “a characterization test is a test that characterizes the actual behavior of a piece of code.” This allows you to take a snapshot of what it does and ensure that it doesn’t change​.

This gives you a safety net so you can refactor with confidence that you’re not introducing regressions​. Use automated test suites to help things run smoothly (unit, integration, end-to-end).

Continuous integration (CI)

It is highly recommended that testing be integrated into a CI pipeline that runs on every commit or merge. This way, you catch a bug during refactoring as soon as you introduce it, tightening the feedback loop.

Canary releases and feature flags

Beyond pre-release testing, consider strategies for safely deploying refactored code. A canary release involves rolling out the change to a small subset of users or servers first, observing it, and then gradually expanding​.

This is great for catching issues that tests might miss (for example, performance issues or edge cases in production data). If the canary looks good (no errors, metrics are healthy), you proceed to full rollout. If not, you rollback quickly—with only a small impact scope.

Performance and load testing

If performance is a concern, incorporate performance tests into your strategy. This can be done in a staging environment. You might reconsider your approach or optimize the new code if you see a significant regression.

Testing legacy code lacking tests

If you’re dealing with a part of the system with zero tests (not uncommon in older code), prioritize getting at least some coverage there. There are also techniques like approval testing (where you generate output and have a human approve it as correct, then use that as a baseline for future tests). The key is not to refactor entirely in the dark; give yourself at least a flashlight in the form of tests!

In sum, a strong testing strategy is non-negotiable for refactoring complex systems. It’s your safety net, early warning system, and guide to know that your “cleanup” hasn’t broken anything vital.

7. Refactoring Without Breaking Performance

A common concern when refactoring is whether these cleaner code changes will make my system slower or more resource-hungry. Ideally, refactoring is about the internal structure and shouldn’t change external behavior, and performance is part of the behavior.

In theory, performance should remain the same if you don’t change algorithms or data structures in a way that affects complexity.

In practice, though, performance can be inadvertently affected by refactoring. The new code may be more readable but uses more memory, or perhaps a critical caching mechanism was removed in the spirit of simplicity.

Senior engineers need to be mindful of performance-sensitive parts of the system when refactoring and take steps to avoid regressions (or even improve performance where possible).

Here’s how to refactor with performance in mind:

Identify performance-critical code paths

Not all codes are equal regarding performance impact. If you refactor them, treat it almost like a functional change: you must re-measure performance afterwards. You have more leeway for parts of the code that run rarely or are not bottlenecks.

Use profiling before and after

A profiler is a tool that measures where time is spent in your code or how memory is allocated. It’s beneficial to run a profiler on the code before refactoring a module to see how it behaves, and then run it after to compare. If you see, for example, that after refactoring, a function now shows up as taking 30% of execution time (when it was negligible before), that’s a red flag. Maybe the new code calls it more times than before.

import cProfile, pstats
from mymodule import slow_function

def profile(fn):
    profiler = cProfile.Profile()
    profiler.enable()
    fn()
    profiler.disable()
    stats = pstats.Stats(profiler).strip_dirs().sort_stats('cumtime')
    stats.print_stats(10)

# run before refactor
profile(lambda: slow_function())

# after you refactor slow_function(), re-run and compare stats

When possible, improve performance through refactoring

On the flip side, refactoring can help performance.

For example, by refactoring duplicated code into one place, you can use better caching in that one place. So, watch for performance improvement opportunities that arise naturally as you refactor.

Performance should be treated as part of the “external behavior” that needs to be preserved in a good mindset. Refactoring should ideally not make things slower for users. To ensure that, incorporate performance checks into your plan, especially for critical sections. Measure, don’t guess. The end goal is a codebase that is both clean and fast enough.

8. Automate Code Reviews with AI tools

Refactoring code is an ongoing process, not a one-time event – AI code review tools help enforce clean-code standards, catch smells early, and reduce the repetitive tasks that can bog down human reviewers. This frees your engineers to focus on deeper architectural or domain-specific issues.

One powerful option is CodeRabbit, an AI-driven review platform designed to cut review time and bugs in half.

Here’s how it works and why it can boost your refactoring workflow:

AI-powered contextual feedback

CodeRabbit analyzes pull requests line by line, applying both advanced language models and static analysis under the hood. It flags potential bugs, best-practice deviations, and style issues before a human opens the PR.

Some other features include:

• Auto-generated summaries and 1-click fixes – Summarize large PRs and apply straightforward fixes instantly.

• Real-time collaboration and AI chat – Chat with the AI for clarifications, alternate code snippets, and instant feedback.

• Integrates with popular dev platforms – Supports GitHub, GitLab, and Azure DevOps for seamless PR scanning.

CodeRabbit even has a free AI code reviews in VS Code and with this VS Code extension, you can get the most advanced AI code reviews directly in your code editor, saving review time, catching more bugs, and helping you in refactoring.

Summary

Refactoring a complex enterprise codebase is like renovating a large building while people still live in it without collapsing the structure.

Refactoring should be an ongoing process. You prevent the codebase from decaying by incorporating these practices into your regular development (perhaps allocating some time each sprint for refactoring or doing it opportunistically when touching your code). Each minor refactoring should not be too complex, and the cumulative effect is significant.

As Martin Fowler puts it, a series of small changes can lead to a significant improvement in design.

That's it for this blog. I hope you learned something new today.

If you want to read more interesting articles about developer tools, React, Next.js, AI and more, then I'll encourage you to checkout my blog.

Some of the new and interesting articles I've written in the last 24 months.

• Cursor vs Windsurf

• How to Implement Role-Based Access Control in Next.js

• AI Code Reviewers vs Human Code Reviewers

• How to Build a Custom Video Conferencing App with Stream and Next.js

• How to Perform Code Reviews in Tech – The Painless Way

You can get in touch if you have any questions or corrections. I’m expecting them.

And if you found this blog useful, please share it with your friends and colleagues who might benefit from it as well. Your support enables me to continue producing useful content for the tech community.

Now it’s time to take the next step by subscribing to my newsletter and following me on Twitter.

Configurable Dependency, also known as Dependency Injection, is a pattern that enables you to switch dependencies of your application. The term was coined by Alistair Cockburn.

Say your application has a GUI. But your administrator wants to use certain functions via the console. Or your production code calls an external service. But your tests shouldn’t call the service, since it doesn’t provide reliable results. Or the service isn’t always available.

Here’s where a Configurable Dependency is helpful. Depending on context, you use one dependency or the other.

A lot of articles attempt to explain the pattern. But they embed it in a broader context, like ports and adapters architecture. That makes understanding harder than necessary. I know, I’ve written such articles myself.

On top of that, many articles focus on greenfield applications. But most of us have to maintain applications that already exist.

Let’s start with a simple class that has a hard-wired dependency. Then we'll refactor it to a class that has a Configurable Dependency.

The example is trivial, but the refactoring steps are generally applicable to your own application if you’re in a similar situation.

I’ll refer to an example GitHub project in the article. It shows the steps to perform, in its commit history. At the end of the article, there are appendices for IntelliJ IDEA and Eclipse. They show how to do the refactoring steps in your IDE.

The Calculator Example

Say you have a class called Calculator. It’s the equivalent of “business logic”. At the end of each calculation, it prints the result to the screen. In a real world application, it might save something to a database instead.

Here’s the code:

package example;

public class Calculator {
    public Calculator(){
    }

    public long add(long one, long two) {
        long result = one + two;
        printResult(result);
        return result;
    }

    public long sub(long one, long two) {
        long result = one - two;
        printResult(result);
        return result;
    }

    private void printResult(long result) {
        System.out.println("The result is: " + result);
    }
}

Now if you want to test that class, your test code may look like this:

package example;

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.*;

class CalculatorTest {
    private Calculator calculator;

    @BeforeEach
    void setup() {
        calculator = new Calculator();
    }

    @Test
    void addsToNumbers() {
        long result = calculator.add(1, 2);
        assertEquals(3, result);
    }

    @Test
    void subtractsToNumbers() {
        long result = calculator.sub(5, 1);
        assertEquals(4, result);
    }
}

Every time you run your test, it prints the results to the screen. That’s unnecessary. It slows your tests down.

With dependency injection, you can still assert the result in the test. But you avoid printing the result to the screen (or saving the result to the database, the file system, or somewhere else).

Step 1: Move Dependency Creation to the Constructor

Find out where an instance of the dependent class is created. Move creation to the constructor by assigning the instance to a field. Use the field throughout the class, so that only the constructor creates the dependency.

The example code is a bit different. The dependency is a static one, System.out. But as described above, the refactored code assigns it to the printer field in the constructor.

So the Calculator class now looks like this:

package example;

import java.io.PrintStream;

public class Calculator {
    private final PrintStream printer;

    public Calculator(){
        printer = System.out;
    }

    public long add(long one, long two) {
        long result = one + two;
        printResult(result);
        return result;
    }

    public long sub(long one, long two) {
        long result = one - two;
        printResult(result);
        return result;
    }

    private void printResult(long result) {
        printer.println("The result is: " + result);
    }
}

Run the test. It still needs to pass.

Step 2: Pass the Dependency as a Constructor Argument

Pass the instance as a constructor argument, instead of creating it in the constructor. Here’s the refactored example code:

package example;

import java.io.PrintStream;

public class Calculator {
    private final PrintStream printer;

    public Calculator(PrintStream printer){
        this.printer = printer;
    }

    public long add(long one, long two) {
        long result = one + two;
        printResult(result);
        return result;
    }

    public long sub(long one, long two) {
        long result = one - two;
        printResult(result);
        return result;
    }

    private void printResult(long result) {
        printer.println("The result is: " + result);
    }
}

For this class to work, you need to adapt each line of code that creates a Calculator object to pass in the dependency. So the line to create the Calculator in CalculatorTest now looks like this:

calculator = new Calculator(System.out);

Run the test. It still needs to pass.

Step 3: Create an Interface and Implementation

Create an interface with the exact same name as the class name of the dependency. Place it in the same package. Put the method in it that the business logic calls.

package example;

public interface PrintStream {
    void println(String text);
}

In the Calculator class, remove the import statement of the dependency, java.io.PrintStream, to use the new interface instead.

Here’s one implementation of the interface. ConsolePrinter contains the original functionality that prints to a screen.

package example;

public class ConsolePrinter implements PrintStream{
    @Override
    public void println(String text) {
        System.out.println(text);
    }
}

In the test class, pass in the ConsolePrinter. Run the test. It still needs to pass, and print the results to the screen:

package example;

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.*;

class CalculatorTest {
    private Calculator calculator;

    @BeforeEach
    void setup() {
        calculator = new Calculator(new ConsolePrinter());
    }

    @Test
    void addsToNumbers() {
        long result = calculator.add(1, 2);
        assertEquals(3, result);
    }

    @Test
    void subtractsToNumbers() {
        long result = calculator.sub(5, 1);
        assertEquals(4, result);
    }
}

Step 4: Rename and Clean Up

This is an optional step. You can decide to rename the interface, to give it a more meaningful name. For example, rename PrintStream to Printer.

You can also decide to move the class to a different package and rename its method(s).

Run the test. It still needs to pass.

Step 5: Configure the Dependency

Create another implementation that ignores the text argument, for testing purposes:

package example;

public class IdlePrinter implements Printer{
    @Override
    public void println(String text) {
        // This is empty, because we don't want to print in tests.
    }
}

Now, you can change a single line of the CalculatorTest to turn off printing:

calculator = new Calculator(new IdlePrinter());

Since Java 8, you don’t even need IdlePrinter. Pass in a Lambda function instead:

calculator = new Calculator(text -> {});

Congratulations!

You have refactored to a Configurable Dependency.

Have a look at the GitHub project commit history to see the changes in code that I performed.

If you have any questions, leave a comment or contact me.

Twitter: https://twitter.com/BertilMuth

LinkedIn: https://www.linkedin.com/in/bertilmuth/

The following appendices explain the concrete refactoring steps in IntelliJ IDEA and Eclipse.

Appendix A — How to refactor in IntelliJ IDEA

IntelliJ Step 1: Move Dependency Creation to the Constructor

Open the Calculator class. Locate System.out. Right click, select Refactor > Introduce Field. Select initialize in: constructor. Name the field printer. Hit Return.

IntelliJ Step 2: Pass the Dependency as a Constructor Argument

Set the cursor into the constructor, Calculator(). Mark the access to the dependency, System.out. Right click, select Refactor > Introduce Parameter. Name the field printer. Hit Return.

IntelliJ Step 3: Create an interface and Implementation

Create the interface and implementation in the same package:

package example;

public interface PrintStream {
    void println(String text);
}

package example;

public class ConsolePrinter implements PrintStream{
    @Override
    public void println(String text) {
        System.out.println(text);
    }
}

Go to the business logic class Calculator and remove the import statement import java.io.PrintStream;. Save the file.

In the test class CalculatorTest, use the new implementation class.

Change this:

calculator = new Calculator(System.out);

to this:

calculator = new Calculator(new ConsolePrinter());

Save the file. Run the test and check if it still passes.

IntelliJ Step 4: Rename and Clean Up

Go to the interface PrintStream. Right click on PrintStream and select Refactor > Rename. Enter Printer and press Return. Run the test and check if it still passes.

IntelliJ Step 5: Configure the Dependency

Create another implementation that ignores the text argument, for testing purposes:

package example;

public class IdlePrinter implements Printer{
    @Override
    public void println(String text) {
        // This is empty, because we don't want to print in tests.
    }
}

Go to CalculatorTest and change this:

calculator = new Calculator(new ConsolePrinter());

to this:

calculator = new Calculator(new IdlePrinter());

Save the file. Run the test and check if it still passes.

The text output should now be off. Well done.

Appendix B — How to Refactor in Eclipse

Eclipse Step 1: Move Dependency Creation to the Constructor

Open the Calculator class. Locate System.out. Right click, select Refactor > Extract Local Variable. Click OK.

Mark the newly created local variable out. Right click, select Refactor > Convert Local Variable to Field. Name the variable printer. Choose Initialize in Class Constructors. Check Declare field as ‘final’. Hit OK.

Run the test and check if it still passes.

Eclipse Step 2: Pass the Dependency as a Constructor Argument

Set the cursor into the constructor, Calculator(). Mark the access to the dependency, System.out, and copy it to the clipboard (CTRL-C).

Right click, select Refactor > Change Method Signature. Click Add. Type PrintStream under Type, printer under Name, and paste System.out under Default value. Click OK and Continue.

Change the constructor to look like this:

public Calculator(PrintStream printer){
this.printer = printer;
}

Save the file. Run the test and check if it still passes.

Eclipse Step 3: Create an Interface and Implementation

Create the interface and implementation in the same package:

package example;

public interface PrintStream {
    void println(String text);
}

package example;

public class ConsolePrinter implements PrintStream{
    @Override
    public void println(String text) {
        System.out.println(text);
    }
}

Go to the business logic class Calculator and remove the import statement import java.io.PrintStream;. Save the file.

In the test class CalculatorTest, use the new implementation class.

Change this:

calculator = new Calculator(System.out);

to this:

calculator = new Calculator(new ConsolePrinter());

Save the file. Run the test and check if it still passes.

Eclipse Step 4: Rename and Clean Up

Go to the interface PrintStream. Right click on PrintStream and select Refactor > Rename. Enter Printer and press Return. Run the test and check if it still passes.

Eclipse Step 5: Configure the Dependency

Create another implementation that ignores the text argument, for testing purposes:

package example;

public class IdlePrinter implements Printer{
    @Override
    public void println(String text) {
        // This is empty, because we don't want to print in tests.
    }
}

Go to CalculatorTest and change this:

calculator = new Calculator(new ConsolePrinter());

to this:

calculator = new Calculator(new IdlePrinter());

Save the file. Run the test and check if it still passes.

The text output should now be off. Well done.

What is Code Refactoring?

Refactoring means organizing your code without modifying its original functionality. Refactoring is the process of making small changes or adjustments to your code without affecting or changing how the code functions while in use.

Why Do You Need to Refactor Your Code?

It Helps Improve Your Code/Program

Refactoring helps you improve the design of your software because developing applications is a difficult task. As you add additional functions, the relevance of the program may be affected. Then, abstractions are no longer as pure as they once were.

You can improve things by refactoring your code regularly to demonstrate a better understanding of the program or code you're working with.

It Gives You a Better Understanding of the Code

If you refactor properly, your code will be more easily understandable afterwards. You can also make the code easier to understand by improving the design.

It is common knowledge that developers read code far more frequently than they write it. As a result, it's in your best interest to keep things as simple as possible, which considerably improves maintainability. Also, people who read it in the future will be grateful.

Refactoring Broadens Your Knowledge

Finally, refactoring is a method of active learning. Even if you didn't write the code, refactoring it gives you a better grasp of what it does.

How Refactoring Helps Your Team

Refactoring is a common activity for software development teams. If done correctly, refactoring your code makes it easier for your team members to understand your code and the changes you've made.

The refactoring stage is often difficult for teams to include in their process. But refactoring, in my opinion, is an essential component of working on any process. Adding comments for me entails leaving the code in a better state than when I found it.

Whatever you do, avoid creating a separation between technical value and business value (creating the feature). You can do this by keeping the code understandable.

Refactoring Best Practices – with Python Examples

If you want to get the most benefit from restructuring your code, you should keep the following in mind:

• Refactor only tested code. Without tests, refactoring code is, to put it bluntly, gambling. If you don't have tests that verify that the before and after are equivalent, you can't be certain you didn't break the code. No matter how disciplined you are, eventually, you'll introduce bugs.
• Minimize refactoring. The modification is riskier the more drastic it is. Divide it into several more compact portions. You get flexibility and mitigation.
• Take little, gradual steps. Check to see if everything is working after making a small code change.
• Observe the guidelines. Don't begin adding functionality while refactoring is still being done. Refactoring has no impact on the system's output. Before moving on to the next challenge, complete this one.

Below is an example of code refactoring using the Define function in Python to find the force (F) required to move an object of mass (m) with an acceleration (a) given by the formula “F = m x a”.

Because we are performing a repeated task, it's a good idea to use a function instead of using only the conditional statement. So when we need to in the future, we just have to call the function out for usage.

Code Before Refactoring:

Notice how the two blocks look nearly identical. What if we’re calculating the “Work done” by a person or machine? Most likely, we’d copy and paste the while loop, changing the variable name and input prompt. Now let's use a function to refactor this.

Code After Refactoring:

Now that our code is simpler to understand, we can start to save some lines of code. What's more, in the future, we'll be able to effortlessly insert our function into another script by just calling out the function, saving us time.

Here are some other tips to keep in mind while refactoring your Python code:

Use List Comprehension Instead of a For Loop

One of the most well-known Python constructs is list comprehension. Compared to several basic for loops, list comprehension provides a cleaner, quicker solution.

The code will run more quickly, existing data won't be altered, and list comprehensions are simpler to understand at a glance once you become used to them.

Below is a simple expression of using list comprehension instead of a For Loop:

Initial code:

In the above example, we loop through a list of integers (numbers) to see if we should enter each one into the odd numbers list.

Refactored code:

In the above-refactored code, the list comprehension is an assignment into the odd numbers. Then we iterate over the "numbers" and set the return (the first item). Then, we can include an if-statement to filter.

Use Def Functions for Repetitive Tasks

Defining functions for repetitive tasks is the first and perhaps most significant refactoring we can perform.

Although functions provide many advantages, from the standpoint of refactoring, we will shorten our code and increase readability. In addition, you only have to update the job once, in the declaration of the function (the example given below).

Initial code:

Refactored code:

Use Ternary Operators Instead of if-else Statements:

You can use an easy if-statement like this to find if an input integer is an "even" or "odd" number instead of an if-else statement:

The ternary operator is used in the code above to determine if an integer is even or odd.

msg will be assigned Even if the condition (to_check% 2 == 0) is true. msg will also be assign Odd if the condition (to check% 2 == 0) is not true.

Note: you can't use the ternary operator to replace any code that uses an if-else expression. For example, if-else statements involving more than two cases.

Use the Enumerate Function Instead of Range():

Python for loops can be complicated, especially if you are coming from another programming language.

Initially, you might have thought to make an index variable and use it to loop through your list. As a result, people often find and utilize the range() method. But it's not a best practice to use this method. Below is an example:

Code Before Refactoring:

Using the index on the initial list makes it more difficult to understand and encourages poor habits like changing original values. Particularly in complex nested data structures.

Additionally, we need to manually change the index's values into "counting numbers."

Code After Refactoring:

The enumerate() method returns the current counter value and each item in the iterable and requires two arguments: the iterable and the initial count value.

Note: It is a typical error to order the temporary count variable first in the for loop and the initial count value second in the function call.

Conclusion

Hopefully, you now understand what code refactoring is along with the importance and reasons for refactoring your code.

Based on the simple Python code above, you should understand that refactoring does not necessarily mean your code needs to be shorter after refactoring – but just somehow simpler and more understandable.

For example, if a test looks like this, it is hard to know what the problem is when it fails, as the test data is all hard coded. The test tells you very little about how the system under test (SUT) should behave, and so doesn’t act as documentation.

assert sut.wake_erosion_rate(0.03) == 0.8

However, if you remove this code smell, and include the calculation in the test, it becomes obvious what the problem is when there is a failure, and the test does now act as documentation.

You might also want to replace the 2.5 and 0.05 with the names of the constants they represent.

ambient_turbuluence = 0.03

assert 
    sut.wake_erosion_rate(ambient_turbuluence) 
    == 2.5 * ambient_turbuluence + 0.05

This article references the excellent XUnit Test Patterns book, which defines the most widely accepted lexicon on unit test patterns and practices.

Example Calculation

The rest of this article will discuss the example ConstructionMarginCalculator class, and will describe refactorings that simplify the tests and allow them to feasibly include the calculations.

The calculation is around 30 lines long, and is worth a quick glance now if you have the time. But if not, don’t worry, the rest of this post will still make sense.

There are a few if statements and a loop, and in total these lead to 2^9, or 512, paths through the code! Eek! It is clearly not feasible (or useful) to test all these, hence the need to find ways to make it easier.

This example code has an initial naive test, which is around 30 lines long. It doesn’t include the calculations, and introducing them would make the test even longer and more complicated, so would be hard to justify.

Each of the following sections describes a refactoring, and includes links to the refactored example code. These build on the existing test refactorings from XUnit Test Patterns.

The refactorings reduce the number of paths through the code and simplify the test. This means that fewer tests are needed, and that the tests become small and simple enough to include the calculations.

Extract Calculation From Loop

The code initially calculates values for a list of steps, which means that any test for it must take on this complication.

The setup of the test is harder, as we have to create a list as opposed to a single value. The assertions are harder as we have to assert on a list as opposed to a single value. Finally, we should have multiple tests (probably for 0, 1, and multiple items in the list).

The easy fix is simply to refactor the code so that it only calculates a single step. This displaces the iteration code to some other place, which might want testing. However, this can be tested using a Mock, so only the iteration needs to be tested (as opposed to the iteration and the calculation), which is simple, and potentially so simple that you don’t need to test it.

This refactoring means that instead of requiring 3 tests (for 0, 1, and multiple items in the list), there is now just one. This reduces the number of paths through the code from 2^9 to 2^7, or 128. This is already a lot better, but still too many to test!

• Refactored Calculation
• Refactored Test

Introduce Mockable Abstractions

The details of the inflation calculation aren’t shown in the example, but they are reasonably complicated.

To avoid this we can change the code to accept an InflationCalculator. The inflation calculation always uses the same date_of_financial_close, inflation_rate and inflation_mode, which means that it can take these in the constructor. This in turn means that the main calculation no longer requires the inflation_rate and inflation_mode.

Then in the tests we can create a mock InflationCalculator. This could for example always return a value of 2, which makes the overall calculation a lot simpler.

It is also easy to imagine that inflation calculations will happen in other parts of the code, so the abstraction will be widely useful.

This step means that instead of 4 conditional branches in the inflation calculation, there is now just one. This reduces the number of paths through the code from 2^7 to 2^3, or just 8. It is also necessary to test the InflationCalculator, and this has 4 branches, so needs 4 tests, but this still only makes 12 tests in total. Yay for loosely coupled code!

We now have a feasible number of tests to write, but including the calculation in the test is still going to be very cumbersome. Luckily we still have some refactorings left up our sleeve.

• Refactored Calculation
• Refactored Test

Test Conditional Branches in Isolation

The code branches based on certain conditionals. We can simply make some of these conditionals False, and then test each branch of the code in isolation. This way, each test only has to include the calculation for the branch that it is concerned with.

For example, we can set in_selling_mode to be False and step.start_of_step to be different to date_of_financial_close. This makes the test simple enough that it is feasible for it to perform the same calculation that the code does.

This in turn means that the test clearly communicates that the turbine_cost_including_margin should be the turbine_costs * fraction_of_spend * inflation. This helps readers understand the calculator, and achieves the goal of Tests as Documentation

At the moment the test is still quite long. However, because we are only testing a small part of the calculation, a lot of this information is now irrelevant (the any_double variable). This means we can now create a Test Data Builder, or use helper functions to make things more concise. We will see an example of this in the next refactoring.

• No Change to Calculation
• Refactored Test

Test Values in Isolation

“Test Conditional Branches in Isolation” is a useful technique, but it can still leave us with some complications if a value is calculated / updated in multiple branches.

A good example of this is balance_of_plant_cost_including_margin, which is set initially, and then updated in the if (in_selling_mode) branch.

Testing balance_of_plant_cost_including_margin in isolation allows the test to concentrate just on this one value / calculation, which means that a lot less setup is required. The Test Data Builder pattern hides Irrelevant Information, and the test becomes more concise and expressive.

Including the calculation continues to make the test clearly communicate its intent and act as documentation. Interestingly the test calculation code is no longer an exact copy of the SUT calculation code, as it already knows that it is in_selling_mode, so doesn’t need a conditional statement. This means that the test is simpler than the code, which helps avoid the Obscure Test smell.

• No Change to Calculation
• Refactored Test

Test Partial Values in Isolation

Sometimes the calculation of individual values is very complex, and can’t be split up by conditional branches. This can make it challenging to include the calculation in the test. construction_profit is a reasonable example of this, which is calculated as follows:

step.turbine_cost_including_margin = 
 turbine_costs * inflation * fraction_of_spend;

step.balance_of_plant_cost_including_margin = 
 balance_of_plant_costs_at_financial_close * inflation * fraction_of_spend;

step.construction_profit = 
 -1 * 
 (step.turbine_cost_including_margin + step.balance_of_plant_cost_including_margin) *
 epc_margin

inflation, fraction_of_spend and epc_margin have a multiplicative effect, so if we set them to 1, they won’t have any effect and we can easily write a test for the rest of the logic.

step.turbine_cost_including_margin and step.balance_of_plant_cost_including_margin have an additive effect, so if we set them to 0, again they won’t have any effect and we can easily write a test for the rest of the logic.

Testing just a portion of construction_profit in isolation allows the test to concentrate just on this part of the calculation, which, as before, makes the test shorter and simpler, and avoids the Obscure Test smell.

• No Change to Calculation
• Refactored Test

Introduce the Blackboard Pattern

The Blackboard pattern is a more involved technique, and is often badly understood. But essentially it involves using a “blackboard” to break the dependencies within complicated calculations.

In this example the construction_profit depends on turbine_cost_including_margin and balance_of_plant_cost_including_margin, which are themselves calculated from the inputs. This makes testing harder.

In order to test the construction_profit you essentially also have to test turbine_cost_including_margin and balance_of_plant_cost_including_margin.

When we introduce the blackboard pattern, one calculator writes the turbine_cost_including_margin and balance_of_plant_cost_including_margin to the blackboard, and when calculating the construction_profit we read these values from the blackboard.

This breaks the connection between the two things, so when testing we can just add values for turbine_cost_including_margin and balance_of_plant_cost_including_margin to the blackboard.

• Refactored Calculation
• Refactored Test

Conclusion

When testing calculations, it is important to include the calculation in the tests. This avoids the Hard Coded Test Data smell, allows the tests to clearly express their intent and achieve Tests as Documentation.

The refactorings described in this article allow you to do this while also making sure that the tests are concise and understandable.

Before I go straight to refactoring, I need you to answer one simple question: What does it mean to develop an application? Usually, this means producing a piece of software that meets requirements by implementing certain features.

And how do we do that? We collect customer requirements, estimate them, and develop features one by one, right? Almost.

Do Not Forget About Bugs

Yes, errors do occur. Depending on the development process, software complexity, technical stack, and many other parameters, the number of bugs may vary.

A business cannot afford critical issues in production. To minimize problems, you should pay particular attention to the QA process. But QA theory claims that it is usually impossible to run 100% test coverage of your apps and prepare for all possible scenarios.

Still, to achieve optimal results, teams spend a lot of time testing software and fixing issues. This is a necessary part of the process that each customer should understand and prioritize.

Mind the Technical Debt

Yet, this coin has a flip side. The longer the development and testing process takes, the more technical debt you incur.

So, what does "technical debt" mean? Technical debt refers to all the quality-related issues you have in your code. Issues which will require spending additional resources in the future.

You incur technical debt for a variety of reasons, such as:

1. The business pushes to release new features faster.
2. Testing is insufficient.
3. The requirements are changing rapidly.
4. The developers are inexperienced.

Technical debt should be documented. If you do not leave to-do's in the code, you will most likely forget about the issue. And even if you have time for it in the future, you will not remember to fix it.

Understand the Importance of Refactoring

Usually, you need to spend some time refactoring the existing code in order to solve code quality issues and thus lower technical debt.

But what is refactoring? It is the process of restructuring the existing code without changing its external behavior. And that is actually something that might be difficult to understand for business people managing the project.

– Will we get any new features?

– No.

– Will we at least fix some bugs?

– Also no.

– What will we get then?

– …

Working with technical debt helps to avoid bugs. And to add fixes or changes to the project, we always need to read the old code.

Therefore, refactoring and maintaining good code quality will help us keep development at a good pace.

Sometimes a business might not need it. For instance, if you're working on a prototype or Proof of Concept, or if there are business priorities that cannot be adjusted, you can do without refactoring.

But in most cases, cutting out refactoring is not a wise thing to do. You might spend a huge amount of time on refactoring if your developers are perfectionists, but this makes no sense either.

Therefore, you need to strike a balance. You should not spend more time refactoring than you will save in the future.

How to Start Refactoring Your React Code

Think about code formatting

Some people add trailing commas, and some don't. Some use single quotes, while others use double quotes for a string.

If you work in a team, maintaining the common code style can be really difficult. And inconsistency in code style can make your code look dirty and hard to read.

So if you haven’t thought about using code formatting tools before, it’s high time to do so. One of the most popular and easy-to-use React refactoring tools is Prettier. You can just add it to the project and it will take care of formatting for you.

Prettier has some default style settings, but you can change them according to your preferences by adding a .prettierrc file with your formatting rules.

A good setup of .prettierrc may look like this:

{ "printWidth": 120,  "singleQuote": true, “trailingComma”: “none” }

You can also automatically reformat the code before committing with pre-commit hooks.

Get rid of unnecessary

’s and ’s

When React 16.2 was released in November 2017, a lot of React developers sighed in relief. Prior to that, for a component to return a list of children, it was necessary to wrap the children in an extra element, such as <div> or <span>.

But with React 16.2 we received improved support for returning components’ children. Now developers can use so-called fragments. They look like empty JSX tags (<> … </>). With the help of fragments, you can pass a list of children to the component without adding extra nodes to the DOM.

Think about names

Don’t be lazy when you're thinking about names for components and variables. Every name should be self-explanatory.

Have you ever seen code snippets like this?

const modifyData = data.map(x => [x.a, x.b]))

What does it do? If you cannot understand the purpose of a variable from its name, it is time to rename it!

This will help you and your team understand the logic more easily. It will also eliminate the time spent making changes to existing components in the future.

Don’t Repeat Yourself

The DRY principle was first formulated in the book The Pragmatic Programmer. It states that "every piece of knowledge must have a single, unambiguous, authoritative representation within a system". In other words, you need to put repetitive code blocks into separate reusable components.

Making your code DRY has a lot of benefits. It can save you a lot of time. If you need to change this code in the future, you will only do that in one place. Also, you will never have to worry that you forgot to make changes in some places. Furthermore, you will keep the components cleaner and increase the readability of code.

To keep your components DRY and small, you can follow two simple rules:

1. If you use a code block more than two times, it’s time to extract it.
2. If you exceed a predefined number of lines in a component (e.g. 100 lines), there is probably logic that can be extracted. Divide it into smaller components by functionality.

Use functional over class components

With the introduction of Hooks in React 16.8, we received access to React class features in functional components. Hooks solve a bunch of problems frequently encountered by developers over the past few years.

For example, the useEffect hook, as the React docs suggest, allows us to group the component logic into small functions based on what pieces are related (instead of grouping the logic based on life-cycle methods). This helps us to better restructure our logic.

All in all, refactoring React components with the help of hooks makes the code cleaner and reduces the amount of code you need to write.

Here is a very basic example: fetching the data after the component has mounted and re-fetching it based on the updated props.

In a class component, we would write something like this:

class BookList extends React.Component {
  componentDidMount() {
    this.props.fetchBooks(this.props.bookGenre);
  }
  componentDidUpdate(prevProps) {
    if (prevProps.bookGenre !== this.props.booksGenre) {
      this.props.fetchBooks(this.props.bookGenre);
    }
  } 
// ... }

With React hooks it will look like this:

const BookList = ({ bookGenre, fetchBooks }) => {
  useEffect(() => {
    fetchBooks(bookGenre);
  }, [bookGenre]);
// ... }

The books fetching logic is now gathered in one place. The useEffect hook will run after mount each time the props [bookGenre] in square brackets change. Much cleaner, isn’t it?

Also, you can extract similar stateful logic and reuse it in different components by creating your custom hooks. You can read more about custom hooks in the official React documentation.

Try to avoid arrow functions in render

Have you ever seen code like this?:

render() {    
  return (
    <div>
      <button onClick={() => this.setState({ flag: true })} />
      ...      
    </div>    
  );  
}

Sure you have. What is the problem with it? Every time a component is rendered, a new instance of such a function is created.

It is not a big deal if the component is rendered one or two times. But in other cases, it can really affect performance. So, if you care about performance, declare the function before using it in render:

changeFlag = () => this.setState({ flag: true })
render() {    
  return (      
    <div> 
      <button onClick={this.changeFlag} />        
      ...      
    </div>    
  );  
}

Make the bundle smaller

If you are using a third-party library, you should not load the entire thing if it isn't necessary. Sometimes you can stumble upon an import which uses only one method from the library, such as:

import lodash form 'lodash'  
...  
const certainProps = lodash.pick(userObject, ['name', 'email']);  ...

Instead, it is better to use the following:

import pick from 'lodash/pick' 
... 
const certainProps = pick(userObject, ['name', 'email']); ...

Now you do not load the whole library, just the method you need.

To Wrap Up

Let's review the steps you should take to refactor your React code:

• Think about code formatting
• Get rid of unnecessary <div>'s and <span>'s
• Think about names
• Don’t Repeat Yourself
• Use functional over class components
• Try to avoid arrow functions in render
• Make the bundle smaller

Yet, ideal refactoring is refactoring that does not occur. As a developer and especially as a tech lead, you should think many steps ahead and try to produce high-quality code. You should also carry out regular code reviews, not only within one team but also between teams.

Do you have an idea for a React project?

My company KeenEthics is an experienced React development company. If you are ready to change the game with your software project, feel free to request an estimate.

You can read more similar articles on my Keen Blog. Allow me to suggest The Value of User Testing or Angular vs React: What to Choose for Your App?

Most importantly, I would like to say "thank you" to Yaryna Korduba and Max Fedas, both outstanding React developers, for coauthoring this article as well as the readers for making it to the end!

Earlier in my career, I faced a sort of career crisis.

I was part of a team creating a large analytics platform in the automotive industry. This application had the typical "enterprise-y" layered architecture you would expect ("Business Layer", "Data Access Layer", "Core", etc.).

You would expect to find business logic - the really important business logic - embedded somewhere inside of the code from these layers. But, usually, the really important business rules were coded into stored procedures.

Stored procedures, if you don't know, is like a function you create inside of a database that uses an SQL-like syntax to process data, store it, etc.

I wondered what the purpose of the layers was. They didn't have any code except for passing data to stored procedures or showing data returned by one.

I started to learn more about object-oriented programming, industry best-practices, SOLID, other programming paradigms, application architecture, etc.

From this career crisis, I discovered that these problems have already been solved! It just takes research, time and practice to learn and grow skilled in them.

Object-Oriented?

One thing I discovered is that all the projects I've been on that were doing "Object-Oriented" programming were not doing true OOP. Just because you use classes doesn't mean you are doing OOP. Especially if you are using stored procedures to encode all your business rules.

A Short Aside: The Great Debate

It needs to be brought up: is object-oriented programming or functional programming better?

For starters, most people don't understand what OOP was intended to be in the first place. Similar to how Agile today is usually misunderstood (e.g. just because you are having daily stand-ups, using story points, kanban, etc. it doesn't mean you are doing Agile).

Alan Kay is considered one of the fathers of OOP. In a certain email, he gave some frank explanations about what OOP was supposed to be.

"I thought of objects being like biological cells and/or individual computers on a network, only able to communicate with messages (so messaging came at the very beginning -- it took a while to see how to do messaging in a programming language efficiently enough to be useful)...

OOP to me means only messaging, local retention and protection and hiding of state-process, and extreme late-binding of all things...

But just to show how stubbornly an idea can hang on, all through the seventies and eighties, there were many people who tried to get by with 'Remote Procedure Call' instead of thinking about objects and messages."

For those familiar with microservices, the actor model, and other advanced programming paradigms, your Spidey sense is tingling. These are actually more closely related to true OOP.

So, is FP better than true OOP?

I don't think so. I think they both have their merits. Many languages today are embracing both paradigms and allowing developers to use the tools and methods that work best for the given problem!

What you'll usually find are classes that expose all their properties or internal data members. An HTTP request or database query will fill-up all the properties, and then, perhaps, something else will work on that object's data.

Instead of what Alan Kay intended to be as little "bundles" that pass messages to each other (see aside above), most developers are using objects as mere "data holders". Glorified variables, as it were.

What you'll also find in many codebases are very generic classes like User, Customer or Order.

Is that bad? Well, yes.

Let me ask you a question:

Is User used in many different unrelated places in your application?

For example, is your User class used in the billing part of your code, the user profile parts, the shipping parts, etc.?

Most systems are doing something like that.

What will end up happening is that, because these classes are so generic, they become dumping grounds for code which we don't know where it belongs.

Instead of taking the time to think about the business need for this new code we've written, often we feel that it's easier to put into our generic classes. It's all shareable, right? And we're all about code-reuse, right?

Coupling

So... what if I changed the User class to conform to some billing logic? What are the chances that I've also broken the shipping feature by changing this class? I don't know, but it's higher than 0%.

This User class has coupled all your features together. This causes lots of problems.

Ideally, we want our code to be orthogonal (that's just a fancy word that means changing code in one place won't affect other unrelated places).

We want to be able to change the shipping feature, for example, and not have to test our entire application again. But, if we're sharing our User class everywhere then, to have confidence that we didn't break stuff, we need to re-test everything.

This leads to a fear of changing code. The fear of making our code better. It also leads to a lot of bugs.

If you are building out the payment feature for your application - you shouldn't have to think about whether you are breaking the shipping feature at the same time! This causes a huge cognitive load that doesn't need to be there.

Another Aside: Warning Sign

Overall, I find that the idea of segmenting your business features/functions via different physical folders or even entirely different projects altogether is best. I've written about this before.

But, when it comes to our code at a deeper level, we can still tend to design our classes and objects in a way that's still too generic and leads to much coupling.

Anytime I find classes that have simple names like User or Customer, a warning signal goes off. I'd much rather see classes that are created for a specific context.

For example, if I saw a class named UserForAuthentication or PaymentsCustomer then I would be more confident that these classes aren't being thrown around and reused in too many contexts.

Here's a basic way that might help get started on analyzing your classes. Take your class name and answer these questions:

Is there a subject? (user, client, order, etc.)

Is there a context for that subject? (shipping, orders, dashboard, etc.)

Is there even perhaps an action being performed on the subject? (as we'll see in more details soon)

If you cannot answer 2 of those questions then I'd say there's a good chance that your class might be doing too much by being too generic.

One Of These Things Is Not Like The Others

There's a programming principle called the Single Responsibility Principle.

When looking at classes or methods that are doing too much, using the SRP as a guiding light can help us to make code that is easier to maintain, less coupled and therefore leads to fewer bugs.

Let's look at a generic User class that might be similar to code you've seen before:

class User {
    public firstName: string;
    public lastName: string;
    public id: number;
    public jwtToken: string;
    public homeAddress: string;
    public creditCardNo: string;

    public getFullName(): string {
        return this.firstName + " " + this.lastName;
    }

    public decodeJwtToken(): string {
        return decode(this.jwtToken);
    }
}

Look familiar?

Given the name of the class, we should start to be suspicious that it's too generic of a class.

You Have Mail

You've been tasked with adding a new business requirement. We need users to be able to pay for their products using PayPal.

This User class is already used in multiple places like the user profile, shipping and payment features.

All we need to do is add the user's PayPal email address to the user. Right?

Breaking It Up

Usually, you will get new business requirements that require more changes to your code than this. But this is a simple example.

If we start changing this User class so that it works with the payment feature then we risk affecting the user profile or the shipping feature (since they use this class too).

What should we do?

The best thing to do here is create a different user class that's used within each specific context.

Out of this should come classes like UserForAuthentication, UserProfileUser, ShippingUser and PaymentUser.

Are those models/classes going to contain similar pieces of data that all of them will need? Sure.

Will they also have pieces of data that are only used in one context? Sure.

For example, the user's id is needed everywhere.

But, the user's home address is only ever needed by shipping. Why then, does the payment feature need access to that data? It doesn't.

Here's what these classes might look like:

class UserProfileUser {
    public firstName: string;
    public lastName: string;
    public id: number;
    public homeAddress: string;

    public getFullName(): string {
        return this.firstName + " " + this.lastName;
    }
}

class ShippingUser {
    public id: number;
    public homeAddress: string;
}

class UserForAuthentication {
    public id: number;
    public jwtToken: string;

    public decodeJwtToken(): string {
        return decode(this.jwtToken);
    }
}

class PaymentUser {
    public id: number;
    public creditCardNo: string;
}

Keep Separate Things Separate

Notice that the home address is needed by UserProfileUser and ShippingUser. Is that bad?

We've had it drilled into us so much that duplicating code is a bad thing. So much so, that it's this idea that's caused the problems we're talking about right now!

Sometimes, it's better to "duplicate" code and/or data - if they are within different contexts. Again, we want to avoid coupling our features and classes together.

Let me ask you a question:

Is it probable that the behavior for the home address within the user profile will be different than the behavior for it in the shipping feature?

The answer: yes.

So then, we are talking about two different things. It's the same raw data but not the same business function or concept.

Shipping needs the home address so that it knows where to send products.

The user profile needs the home address so the user can update its values from a UI.

Not the same things.

Also, consider that it might also make sense to add an address to the PaymentUser class too. But, should this context share the same address as shipping?

Well, is it possible that your shipping address wouldn't be the same address you want to bill to? Sure! This happens all the time!

Using the Single Responsibility Principle, we see that these two concepts/responsibilities should be kept separate.

Also, notice that most of our pieces of data are not being shared. The JWT token, for example, is only needed for authenticating a user. Why would we ever need that piece of data inside our Shipping feature's code?

Now, that information is isolated.

Also, any methods that act on that data will also be moved and not inappropriately called by another feature's code.

This was a simple example, and in most cases, this can get a little trickier than we might want. In the end, though, keeping different business concepts separate from each other will make your code easier to understand within a specific context, easier to maintain and will become less error-prone!

This is an excerpt from my book "Refactoring TypeScript: Keeping Your Code Healthy". This section of the book has more techniques for you to help deal with these kinds of dumping grounds. If you enjoyed this article then check out the book for more content like this!

You can connect with me on Twitter too.

When I work on projects, I often run into legacy code that can be improved — to be more readable, more testable, or more compliant with the current coding style. My urge to refactor the code is especially strong after spending a good amount of time trying to understand a piece of obscure code. That code hurts my brain, and I don’t want the same thing to happen to other developers. There is (the adaptation of) the famous Boy Scout Rule: Leave Code Better than You Found It.

But at the same time, I also want to stay focused and make progress on my current projects. I worry that I might get distracted and spend too much time refactoring.

This is a dilemma I often face. I want to be the good samaritan leaving code better than I found it, an engineer turning all the messy code I come across into something clean and elegant. But I also want to stay pragmatic and ship projects quickly.

Balancing between refactoring the legacy code I come across and staying focused on my current project can be hard.

A recent conversation with my manager on this topic provided me guidance to find that balance. Here are a few points I find helpful.

You don’t have to make the code perfect. Small improvements are still useful.

After I read a piece of legacy code, my brain immediately thinks about how it should be ideally. But refactoring that code from its current state to the ideal state sometimes requires an extensive refactoring. At its best, the required refactoring can be time-consuming. At its worst, it can turn into a rabbit hole that causes a big delay on the project.

When I face cases like this, I used to either take a chance and do the extensive refactoring anyway or hold my nose and let the code stay stinky. Now I realize there is a happy middle point: I don’t have the make the code perfect. I can spend as much or as little time as I can afford to make the code a bit better.

Small improvements I do can be still useful for the developers that come next. And those developers may have time to improve the code further, building upon the improvements I make.

(PS: There’s no perfect nor ideal code. The moment you make a change, you see more improvements you can make.)

Time-box your refactoring.

Time-boxing is a great technique to avoid rabbit holes. Before starting to refactor, do a quick estimation about how much time you can spend on refactoring legacy code without delaying the project too much. Write that number down.

Time-boxing your refactoring gives you the peace of mind knowing the main project will stay on track. And that makes the refactoring experience more enjoyable.

Bake the refactoring time into the project estimation.

Things can be even easier if you bake the refactoring time into the project estimation before starting a project. While estimating how much time a project might take, take a quick look at the code you need to touch: when was it first written? How readable and extensible is it? How much test coverage does it have? Unless there’s a hard requirement about when the project needs to be shipped, you should bake some refactoring time into the project’s timeline.

After all, as we keep building upon a legacy codebase, refactoring it as we go is the best way to keep it healthy. And a healthy codebase, in turn, makes building new features faster and safer.

Refactoring is educational.

Refactoring a piece of code is the best way to understand it. Compared to staying aloof and just reading a piece of code, coming in and modifying it gives you a much deeper and intimate relationship with the code.

When you try to add your touch to the code, you will start to notice things you missed before. You may see the constraints and may even understand why the author originally wrote the code this way.

Although refactoring a piece of code doesn’t seem to add any immediate value to the business, it’s an opportunity for you to gain a piece of domain knowledge you currently don’t have. Gaining that domain knowledge is invaluable to both you and the business.

Refactoring is a muscle you can build

The more you do it, the faster you become. One last reason to refactor legacy code is to use it as an opportunity to strengthen your “refactoring muscle”. Investing in building your “refactoring muscle” has a self-reinforcing compound effect: the more you refactor, the better you are at refactoring, making your next refactoring faster. The more you do it, the better the codebase is, making building future features faster.

Luckily, my next project relates to code from almost three years ago. I expect to face many cases requiring me to balance between refactoring legacy code and making progress on the project. I will share my new learning on my personal blog (NOT medium). Subscribe to follow along!

My career plan for the year is to grow into a tech lead. I’m excited about all the learnings ahead and would love to share this journey with you in a brutally honest fashion. I will be sharing my weekly learning on my personal blog (NOT medium).

In the next few months, I will focus on growing in the following areas, so you can expect to see posts related to them:

• focusing on the big picture of the project instead of near-term implementation details;
• balancing my efforts between leading projects and coding;
• work-life balance for long-term productivity;
• the human side of software development: making sure everyone riding with me enjoys the ride and feels fulfilled and inspired.

Originally published at www.sihui.io on February 1, 2019.