<![CDATA[ refactoring - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ https://cdn.freecodecamp.org/universal/favicons/favicon.png <![CDATA[ refactoring - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ Eleventy Fri, 23 Oct 2026 06:34:17 +0000 60 <![CDATA[ How to Migrate a Legacy Monolith Incrementally Without a Big-Bang Rewrite ]]> https://www.freecodecamp.org/news/migrate-legacy-monolith-incrementally/ 6aac7747d406d7c207351312 Thu, 17 Sep 2026 23:27:03 +0000 Large legacy migrations often fail long before the final cutover.

The failure usually starts when the migration is framed as a single event. Move the application. Move the database. Move all the users. Switch the traffic. Turn the old system off.

That creates a dangerous assumption: the legacy system and the new system need to exchange places all at once.

They usually don't.

If you already understand the legacy behavior, protect it with characterization tests, create migration-friendly boundaries, and compare old and new implementations, you have another option.

You can migrate one capability at a time. That changes the problem completely.

Instead of:

legacy monolith
      ↓
complete rewrite
      ↓
big-bang cutover

you can move toward:

legacy monolith
      ↓
one capability extracted
      ↓
small percentage of traffic
      ↓
observe
      ↓
expand
      ↓
repeat

The goal isn't to make the migration slower. The goal is to make each change smaller, observable, and reversible.

In this tutorial, I'll show you how to migrate a legacy monolith incrementally by:

  • choosing a safe first migration slice

  • defining a boundary between legacy and new code

  • routing requests between implementations

  • using the Strangler Fig pattern

  • migrating by business capability instead of technical layer

  • keeping old and new implementations running together

  • introducing progressive traffic

  • detecting failures before full cutover

  • designing rollback paths

  • handling data ownership carefully

  • removing migrated legacy behavior

  • using AI without turning an incremental migration into an automated rewrite

The examples use TypeScript, but the approach applies to most languages, runtimes, and architectures.

The objective is simple: make migration a sequence of controlled changes instead of one irreversible event.

Prerequisites

To follow along, you should be comfortable with:

  • TypeScript or a similar language

  • API and service boundaries

  • integration testing

  • dependency injection

  • routing and reverse proxies

  • database transactions

  • observability

  • incremental refactoring

  • legacy modernization

You should also already understand the behavior of the capability you want to migrate.

Ideally, you know:

  • its inputs

  • its outputs

  • its important business rules

  • its side effects

  • its dependencies

  • its external contracts

  • how you'll detect behavioral differences

If you haven't reached that point yet, migration may be premature.

Table of Contents

Why Big-Bang Migrations Are So Risky

Imagine a legacy commerce application.

It contains:

customers
orders
payments
inventory
shipping
invoicing
notifications
reporting

The modernization plan says:

replace the monolith

That sounds like one project.

Operationally, it may mean changing:

runtime
framework
database
deployment model
API contracts
authentication
networking
observability
data model
business logic
external integrations

at the same time.

If the final cutover fails, the number of possible causes is enormous.

For example:

Did pricing change?

Did the database migration lose data?

Is the payment provider failing?

Did authentication behave differently?

Did the new runtime change date handling?

Did a timeout become shorter?

Did an event stop being published?

Did the new deployment configuration fail?

This is one of the central problems with big-bang migration: too many variables change together.

Incremental migration tries to reduce the number of changing variables at each step.

Think in Migration Slices, Not Applications

Instead of asking:

How do we migrate this monolith?

ask:

What's the smallest meaningful business capability we can move independently?

For example:

Calculate Order Total
Generate Invoice
Send Order Confirmation
Create Shipment
Renew Subscription
Approve Customer

A migration slice should ideally have:

clear input
clear output
known side effects
understood dependencies
observable behavior
a rollback path

That gives you something concrete to move.

For example:

Generate Invoice

might become:

input:
orderId

behavior:
load order
calculate taxes
generate invoice number
create invoice

side effects:
store invoice
publish invoice.created

output:
invoice

That's much easier to migrate than:

billing module

or:

src/services/

Business capabilities make better migration units than folders.

Choose the First Capability Carefully

The first slice matters.

I would usually avoid starting with the most critical capability in the system.

You want something meaningful enough to validate the migration approach, but not so dangerous that a mistake creates catastrophic consequences.

A useful first slice often has:

moderate traffic
limited external dependencies
clear behavior
good test coverage
few transactional boundaries
low blast radius

For example:

Generate Customer Statement

may be a better first migration candidate than:

Authorize Payment

The first migration is partly technical work, but it's also a learning exercise.

You're validating:

routing
deployment
observability
rollback
data access
testing
team workflow

before applying the pattern to more critical capabilities.

Create a Boundary Between Legacy and New

Suppose the legacy application has:

async function generateInvoice(
  orderId: string
) {
  // legacy implementation
}

Before migration, introduce a boundary:

interface InvoiceGenerator {
  generate(
    orderId: string
  ): Promise<Invoice>;
}

The legacy implementation becomes:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // existing behavior
  }
}

The new implementation becomes:

class NewInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // migrated behavior
  }
}

Now the caller doesn't need to know which implementation is active.

That creates an important capability:

replace implementation
without replacing caller

which is one of the foundations of incremental migration.

Use the Strangler Fig Pattern

A common way to describe incremental replacement is the Strangler Fig pattern.

Instead of replacing the entire application at once, new behavior gradually grows around the old system.

Conceptually:

            incoming request
                   │
                   ↓
                router
              /        \
             /          \
      legacy path     new path

At first:

legacy: 100%
new:      0%

Later:

legacy: 95%
new:      5%

Then:

legacy: 50%
new:     50%

Eventually:

legacy:  0%
new:    100%

At that point, the old implementation for that capability can be removed.

The key is that the replacement happens gradually. The legacy application continues serving parts of the system while the new implementation takes over others.

Migrate Capabilities, Not Technical Layers

One tempting migration strategy is:

move database
then move services
then move APIs
then move UI

That can create long periods where every capability spans both old and new architecture.

For example:

new API
↓
legacy service
↓
new database
↓
legacy event publisher

This is sometimes unavoidable.

But whenever possible, I prefer vertical slices.

A vertical slice might be:

Generate Invoice

request
↓
application logic
↓
persistence
↓
events
↓
response

That capability can move as one coherent unit.

Then:

Create Shipment

can move separately.

Then:

Renew Subscription

and so on.

This gives you working migrated capabilities earlier. It also reduces the number of temporary cross-system dependencies.

Keep Legacy and New Implementations Running Together

During an incremental migration, coexistence is normal.

For some period of time, you may have:

LegacyInvoiceGenerator
NewInvoiceGenerator

both deployed.

That's not duplication by accident. It's part of the migration strategy.

The important question is how requests choose between them.

You may use:

feature flag
tenant
user group
request header
region
percentage rollout
specific account IDs

For example:

class InvoiceRouter {
  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    orderId: string,
    useMigrated: boolean
  ) {
    if (useMigrated) {
      return this.migrated.generate(
        orderId
      );
    }

    return this.legacy.generate(
      orderId
    );
  }
}

This is deliberately simple. The important part is that routing is explicit. You know which implementation handled each request.

Route Traffic Explicitly

Avoid migration logic that's difficult to observe.

For example:

try {
  return await newService.call();
} catch {
  return legacyService.call();
}

This may look resilient, but it can hide failures.

Suppose the new implementation fails 40% of the time. If every failure silently falls back to legacy, users may see no problem. But the migration isn't healthy.

The problem is that the first version mixes two decisions together: which implementation should receive the request and what should happen when that implementation fails. Because the fallback happens inside the catch, the migrated path can fail repeatedly without producing an explicit routing signal that you can measure.

A better approach is to make the routing decision first, record it, and then call the selected implementation. That separates migration policy from error handling and gives you a clear record of how much traffic actually reached each path.

For example:

const route =
  migrationPolicy.route(request);

metrics.increment(
  `invoice.route.${route}`
);

if (route === "migrated") {
  return migrated.generate(
    request.orderId
  );
}

return legacy.generate(
  request.orderId
);

Now you can measure:

requests routed to legacy
requests routed to migrated
migration failures
fallback count
latency
business outcomes

Migration should be observable as a first-class system behavior.

Start with Internal or Low-Risk Traffic

Before routing a large percentage of customers to the migrated path, start with safer traffic.

For example:

development
test environments
internal users
staff accounts
test tenants
specific low-risk customers

This lets you validate:

deployment
routing
observability
data access
external integrations
failure handling

with lower risk.

You can then expand.

For example:

internal users
↓
1% production
↓
5%
↓
10%
↓
25%
↓
50%
↓
100%

The exact percentages aren't important, but the principle is.

Each increase should happen because the previous stage produced enough evidence.

Progressively Increase Production Traffic

Suppose you have:

10,000 invoice requests/day

Instead of switching all requests:

legacy → new

at once, route:

1%

first.

That gives roughly:

100 real requests/day

through the migrated path.

Now monitor:

error rate
latency
output differences
side effects
customer-visible failures
business metrics

If the system behaves correctly, increase traffic. If it doesn't, reduce or disable migrated routing.

The migration becomes a controlled experiment. That's very different from a cutover event.

Use Differential Testing Before and During Rollout

The previous article in this series focused on differential testing. That technique becomes especially useful here.

Differential testing means running the legacy and migrated implementations with the same input and comparing their observable behavior. Depending on the capability, that may include return values, errors, state changes, and side effects.

The goal isn't to prove that the implementations are internally identical. It's to detect meaningful behavioral differences before those differences reach all of your production traffic.

Before live routing, you can compare:

same input
↓
legacy result

same input
↓
new result

During rollout, you can also sample real traffic and compare behavior where it is safe to do so.

For example:

real request
      │
      ├────→ active implementation
      │
      └────→ shadow implementation

Then compare:

output
errors
side effects
business state

This gives you evidence before increasing traffic.

A rollout decision can then be based on:

divergence
error rate
latency
business outcomes

instead of:

It seems fine.

A Small End-to-End Invoice Migration Example

The individual pieces are easier to understand when you see them working together.

Here's a deliberately small, in-memory example based on the invoice capability we've been using throughout the article. It doesn't include a real database, reverse proxy, queue, or deployment platform. The point is to show the migration control flow in one place.

Start with a shared contract:

type InvoiceInput = {
  orderId: string;
  subtotal: number;
};

type Invoice = {
  orderId: string;
  total: number;
};

interface InvoiceGenerator {
  generate(
    input: InvoiceInput
  ): Promise<Invoice>;
}

The legacy implementation calculates the invoice total like this:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    return {
      orderId: input.orderId,
      total: input.subtotal * 1.21,
    };
  }
}

Now imagine we've migrated that capability into a new implementation:

class MigratedInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const tax =
      input.subtotal * 0.21;

    return {
      orderId: input.orderId,
      total: input.subtotal + tax,
    };
  }
}

The code is different, but the intended behavior is the same.

Next, define a deterministic rollout function. This example assigns each orderId to a bucket from 0 to 99 so the same order always follows the same route:

function bucketFor(
  value: string
): number {
  const sum = [...value].reduce(
    (total, char) =>
      total + char.charCodeAt(0),
    0
  );

  return sum % 100;
}

function shouldUseMigrated(
  orderId: string,
  percentage: number
): boolean {
  return (
    bucketFor(orderId) < percentage
  );
}

If percentage is 10, roughly 10% of IDs will be assigned to the migrated path.

Now add some tiny in-memory metrics:

const metrics = {
  legacyRequests: 0,
  migratedRequests: 0,
  mismatches: 0,
};

Then put the legacy and migrated implementations behind one migration-aware entry point:

class IncrementalInvoiceService {
  migratedEnabled = true;
  rolloutPercentage = 10;

  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const legacyResult =
      await this.legacy.generate(
        structuredClone(input)
      );

    const migratedResult =
      await this.migrated.generate(
        structuredClone(input)
      );

    if (
      migratedResult.orderId !==
        legacyResult.orderId ||
      migratedResult.total !==
        legacyResult.total
    ) {
      metrics.mismatches += 1;
    }

    const useMigrated =
      this.migratedEnabled &&
      shouldUseMigrated(
        input.orderId,
        this.rolloutPercentage
      );

    if (useMigrated) {
      metrics.migratedRequests += 1;
      return migratedResult;
    }

    metrics.legacyRequests += 1;
    return legacyResult;
  }
}

This small service combines several ideas from the article.

First, it runs both implementations with the same input and compares their results. Because this example is entirely in memory and has no external side effects, doing that is safe.

Second, it routes only a percentage of requests to the migrated result.

Third, it records how many requests used each path and how many behavioral mismatches occurred.

You can exercise it with a few requests:

const service =
  new IncrementalInvoiceService(
    new LegacyInvoiceGenerator(),
    new MigratedInvoiceGenerator()
  );

for (let i = 1; i <= 100; i++) {
  await service.generate({
    orderId: `order-${i}`,
    subtotal: 1000,
  });
}

console.log(metrics);

You might see something like:

legacyRequests:   89
migratedRequests: 11
mismatches:        0

The exact split may not be exactly 90/10 with only 100 inputs because the bucket function is intentionally simple. The important point is that routing is deterministic, measurable, and controlled by rolloutPercentage.

If the migrated implementation starts producing differences, the mismatch counter gives you an observable signal.

And if you decide the rollout should stop, rollback is explicit:

service.migratedEnabled = false;

From that point forward, all returned responses come from the legacy implementation again.

This is intentionally a simplified example. A production system would need stronger routing, real metrics, error handling, persistent state, and careful treatment of side effects.

In particular, you shouldn't blindly execute both implementations if generating an invoice sends email, writes to two production databases, charges a customer, or publishes externally visible events. In those cases, the shadow path needs recording adapters, isolated infrastructure, or another mechanism that lets you compare behavior without duplicating real effects.

But the control loop is the same:

same input
↓
compare legacy and migrated behavior
↓
route a small percentage
↓
observe
↓
expand or roll back

That is incremental migration in its smallest useful form.

Design Rollback Before You Need It

Rollback shouldn't be invented during an incident. Before moving traffic, ask what happens if the migrated path fails.

For routing-level migrations, rollback may be simple:

migration flag = false

and traffic returns to:

legacy implementation

For example:

if (
  featureFlags.useNewInvoices
) {
  return migrated.generate(
    orderId
  );
}

return legacy.generate(orderId);

If the migrated path behaves incorrectly:

useNewInvoices = false

Rollback is almost immediate.

But rollback becomes more complicated when:

data format changes
new data is written
events differ
external systems are updated
legacy code cannot read new records

In those cases, rollback may require more than flipping a feature flag. You might need backward-compatible schemas so both versions can read the same records, compensating actions for external side effects, replayable events, reconciliation jobs, or a short period where the legacy system remains able to consume data written by the new path.

For higher-risk migrations, it can also help to define a rollback boundary in advance. For example: traffic can return to legacy until a new schema version is written, or after a particular external event is emitted, recovery requires compensation instead of a simple rollback. The important part is knowing when rollback is still reversible and when you've crossed into a different recovery strategy.

That's why rollback design needs to happen before deployment.

Treat Data Migration as a Separate Problem

Application migration and data migration are related, but they aren't the same problem.

Suppose the legacy system stores:

{
  "customer_type": "P",
  "status": 2
}

while the new system stores:

{
  "customerType": "PREMIUM",
  "status": "APPROVED"
}

You now need to answer:

Which database is authoritative?

Can both systems read the same data?

Do we transform on read?

Do we migrate records in batches?

Do we replicate changes?

When does ownership change?

These decisions should be explicit. Otherwise the application migration may appear successful while the data boundary remains ambiguous.

Be Careful with Dual Writes

One common transition strategy is:

write to legacy database
+
write to new database

This is called dual writing, and it looks simple.

For example:

await legacyOrders.save(order);
await newOrders.save(order);

But what happens if:

legacy write succeeds
new write fails

Now the two systems disagree.

Or:

legacy write fails
new write succeeds

Same problem.

Dual writes create a distributed consistency problem.

If you use them, you need to think about:

retries
idempotency
reconciliation
ordering
partial failure
monitoring

Sometimes a safer approach is:

single authoritative write
↓
change event
↓
replication

or a transactional outbox.

There's no universal solution. The important point is not to treat dual writing as a trivial migration technique.

Decide Who Owns the Data

During coexistence, data ownership can become confusing.

Imagine:

legacy system writes customers

new system writes invoices

both systems read orders

That may be perfectly reasonable, but it should be documented.

For each migrated capability, define:

system of record
write owner
readers
replication direction
consistency expectations

For example:

Invoices

Write owner:
new system

Source of truth:
new database

Legacy access:
read-only adapter

Replication:
new → legacy reporting store

Now the architecture has an explicit direction.

Without ownership rules, migrations often create permanent synchronization problems.

Observe Business Behavior, Not Just Infrastructure

During rollout, teams often monitor:

CPU
memory
latency
HTTP 500s
database connections

Those are important. But they're not enough.

Suppose:

HTTP 200 rate = 99.99%

while:

invoice totals are wrong

Infrastructure monitoring says:

healthy

But the business system is not healthy.

Migration observability should include domain signals.

For example:

orders processed
payments authorized
invoices generated
discount distribution
failed renewals
average invoice total
events published

If you know normal business behavior, unusual changes can expose migration defects that technical metrics miss.

Know When a Migration Slice Is Complete

A capability isn't fully migrated just because traffic reached 100%.

Before declaring it complete, I would verify:

100% traffic on new path
acceptable error rate
acceptable latency
behavioral differences resolved
side effects verified
data ownership established
rollback window completed
legacy callers removed
legacy writes stopped
observability in place

Then ask:

Is the legacy implementation still serving any purpose?

If not, remove it.

Leaving both implementations permanently active creates:

maintenance cost
confusion
duplicate bugs
unclear ownership
future migration debt

Incremental migration should eventually simplify the system, not permanently duplicate it.

Remove the Legacy Path

This step is often delayed.

Teams migrate traffic but leave the old path in place:

just in case

Months later:

nobody knows whether it is still used

Before deleting it, verify:

routing metrics show zero traffic
no callers depend on it
data dependencies are removed
rollback period is complete
operational documentation is updated

Then remove:

legacy implementation
legacy feature flags
legacy database access
unused integration code
temporary compatibility layers

Deletion is part of migration.

A migration that only adds new architecture without removing old architecture can increase complexity rather than reduce it.

How to Use AI During an Incremental Migration

AI can help with many parts of this process.

For example, it can inspect the legacy codebase and help answer:

Which modules implement this capability?

Which callers depend on it?

Which database tables does it touch?

Which external services does it call?

Which side effects occur?

Which feature flags already exist?

Which paths need adapters?

A useful prompt might be:

Analyze the Generate Invoice capability.

Identify:

1. entry points,
2. business rules,
3. persistence dependencies,
4. external integrations,
5. side effects,
6. callers,
7. data ownership,
8. possible migration seams.

Do not redesign the system.

Return evidence for each finding using file paths
and relevant code references.

AI can also help compare migration changes.

For example:

Compare the legacy and migrated implementations.

Identify possible behavioral differences in:

- return values,
- errors,
- side effects,
- persistence,
- event ordering,
- retries,
- idempotency,
- transaction boundaries.

Do not assume the new implementation is correct.

This is useful because migration involves a lot of repetitive analysis, and AI can accelerate that analysis.

Don't Let AI Turn the Migration into a Rewrite

There's a common failure mode.

You ask:

Help me migrate this legacy capability.

The model responds with:

new architecture
new domain model
new API
new event model
new database schema
new validation layer
new framework

At that point, you're no longer migrating one capability, you're redesigning it.

Sometimes redesign is necessary, but it should be intentional.

During incremental migration, I prefer prompts with explicit constraints.

For example:

Migrate this capability without intentionally changing
observable behavior.

Preserve:

- inputs,
- outputs,
- errors,
- side effects,
- ordering where relevant,
- transactional behavior.

Only introduce the minimum structural changes required
to run it in the target environment.

List any behavior you cannot preserve with confidence.

That keeps the transformation narrow.

AI should help reduce mechanical effort. It shouldn't silently expand project scope.

A Practical Incremental Migration Workflow

Here's the workflow I would use.

1. Understand the Capability

Identify:

inputs
outputs
rules
side effects
dependencies
unknowns

2. Characterize Existing Behavior

Protect important behavior with:

characterization tests
integration tests
contract tests

3. Refactor for Migration

Create:

seams
adapters
explicit dependencies
clear orchestration

without intentionally changing behavior.

4. Build the New Implementation

Implement the capability in the target environment. Keep its observable contract clear.

5. Differentially Test Old and New

Compare:

outputs
errors
side effects
business state

using representative cases.

6. Introduce Explicit Routing

Allow requests to choose:

legacy
or
migrated

through an observable migration policy.

7. Start with Safe Traffic

Use:

internal users
test tenants
selected customers

8. Increase Traffic Gradually

For example:

1%
5%
10%
25%
50%
100%

only when evidence supports the next stage.

9. Monitor Technical and Business Metrics

Observe both:

system health
business behavior

10. Keep Rollback Available

Make returning to the legacy path fast and understood.

11. Transfer Data Ownership

Explicitly define which system owns:

writes
reads
replication

12. Remove the Legacy Path

After the migration has stabilized:

delete old implementation
remove temporary routing
remove obsolete dependencies

Then choose the next capability.

What Incremental Migration Doesn't Solve

Incremental migration reduces risk, but it doesn't eliminate complexity.

You may still need to deal with:

distributed transactions
shared databases
old schemas
tight coupling
unsupported runtimes
poor test coverage
organizational ownership
regulatory constraints

There are also systems where partial migration is extremely difficult.

For example:

highly stateful systems
strongly coupled desktop applications
large transactional batch systems
systems with shared global state

Sometimes the migration boundary needs to be larger.

The principle remains the same:

Make the smallest reversible change that produces useful migration progress.

Incremental doesn't always mean tiny. It means controlled.

The Complete Legacy Modernization Workflow

This article closes the workflow we've been building throughout this series.

We started with a basic problem:

How do you modernize a legacy application without accidentally turning the project into a rewrite?

The first step was understanding.

Legacy system
↓
investigate
↓
map behavior and dependencies

Then characterization.

observed behavior
↓
tests
↓
behavioral safety net

Then refactoring.

entangled capability
↓
seams and boundaries
↓
migration-friendly structure

Then differential testing.

legacy implementation
        +
new implementation
        ↓
behavior comparison

And finally incremental migration.

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Route
↓
Observe
↓
Expand
↓
Remove legacy

The sequence matters.

If you skip understanding, you may migrate the wrong behavior.

If you skip characterization, you may not notice behavioral changes.

If you skip refactoring, the migration boundary may remain too large.

If you skip comparison, differences remain hidden.

If you skip incremental rollout, you discover problems at full blast radius.

Each step reduces a different kind of uncertainty.

Conclusion

Modernizing a legacy application doesn't require replacing everything at once.

In many cases, the safer strategy is to create a path where old and new implementations can coexist temporarily.

Move one capability, then compare it.

Route a small amount of traffic and observe what happens.

Increase traffic when the evidence supports it, and roll back when it doesn't.

Transfer ownership explicitly, then remove the legacy path.

And repeat.

The full workflow becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate incrementally
↓
Compare behavior
↓
Progressively route traffic
↓
Observe
↓
Remove legacy

AI can make every stage faster.

It can help map code, identify dependencies, generate adapters, compare implementations, analyze failures, and inspect migration diffs.

But speed isn't the same as confidence.

The important decisions still require engineering judgment:

What behavior matters?

What can change?

What should remain compatible?

What is the migration boundary?

What evidence is enough?

When is rollback necessary?

When can the legacy path be removed?

Those aren't code-generation questions. They're migration decisions.

And that's the larger lesson behind this entire series.

AI makes it increasingly cheap to produce new code. But that doesn't make legacy modernization trivial. It makes the quality of the decisions around the code more important.

Because the safest migration is rarely the one that changes the most software. It's the one that lets you change the system while continuously knowing what changed, why it changed, and whether it's safe to keep going.

]]> <![CDATA[ How to Refactor a Legacy Application Before Migrating It ]]> https://www.freecodecamp.org/news/refactor-legacy-application-before-migration/ 6a9f3503813f6309fdfcd6e3 Mon, 07 Sep 2026 22:04:51 +0000 The moment a team decides to migrate a legacy application, there's usually pressure to start moving code.

Move the database, the API, or the UI. Move the application to a new framework, runtime, cloud provider, or architecture.

That sounds reasonable, but there's a problem.

If the current system mixes business rules, persistence, infrastructure, external integrations, and orchestration inside the same modules, migration becomes much harder than it needs to be.

You're not just moving software. You're trying to move several responsibilities that have become entangled over years of development.

This is why I often prefer to refactor before migrating. Not to make the legacy system beautiful or redesign everything. And definitely not to turn the preparation phase into another rewrite.

The goal is much narrower: change the structure enough that important behavior can move independently.

In the previous steps of this workflow, we first tried to understand the codebase and then used characterization tests to protect the behavior we were about to change.

Now you'll learn how you can start changing the structure.

In this tutorial, I'll show you how to prepare a legacy application for migration by:

  • choosing a migration boundary,

  • separating business rules from infrastructure,

  • introducing seams,

  • isolating side effects,

  • creating adapters around external systems,

  • reducing dependency direction problems,

  • extracting cohesive application behavior,

  • using characterization tests throughout the refactor,

  • using AI without letting it redesign the system blindly,

  • and knowing when the application is ready to start migrating.

The examples use TypeScript, but the process applies to most languages and architectures.

The objective is not:

legacy application
↓
perfect architecture

Instead, it's:

legacy application
↓
migration-friendly structure
↓
incremental migration

That difference can save a lot of unnecessary work.

Prerequisites

You should be comfortable with:

  • reading an existing codebase

  • TypeScript or a similar language

  • unit and integration testing

  • dependency injection

  • interfaces and adapters

  • basic software architecture

  • incremental refactoring

You should also have some behavioral protection around the capability you plan to modify.

That may include:

  • characterization tests

  • integration tests

  • contract tests

or another reliable way to verify existing behavior.

Refactoring without that protection is possible. But it's also much harder to distinguish a structural improvement from an accidental behavioral change.

Table of Contents

Why Migration Problems Often Start Before the Migration

Imagine you need to migrate an order-processing application.

You inspect the main service and find something like this:

async function processOrder(orderId: string) {
  const connection = await mysql.getConnection();

  const [rows] = await connection.query(
    "SELECT * FROM orders WHERE id = ?",
    [orderId]
  );

  const order = rows[0];

  if (!order) {
    throw new Error("Order not found");
  }

  if (order.customer_type === "PREMIUM") {
    order.total = order.total * 0.9;
  }

  if (
    order.country === "AR" &&
    order.payment_method === "TRANSFER"
  ) {
    order.total -= 500;
  }

  await connection.query(
    "UPDATE orders SET total = ?, status = ? WHERE id = ?",
    [order.total, "PROCESSED", order.id]
  );

  await paymentProvider.createPayment({
    orderId: order.id,
    amount: order.total,
  });

  await eventBus.publish("order.processed", {
    id: order.id,
    total: order.total,
  });

  await emailClient.send({
    to: order.customer_email,
    template: "order-processed",
  });

  return order;
}

Suppose the migration goal is:

MySQL       → PostgreSQL
Old runtime → New runtime
Legacy API  → New service

The obvious temptation is to begin translating this function into the target stack.

But what exactly are you migrating?

The function contains:

database access
business rules
state transition
payment integration
event publication
email delivery
application orchestration

Changing the database now risks affecting pricing, while changing the payment client risks affecting persistence. And moving the function into another service means moving all of its dependencies at once.

The migration difficulty is partly caused by the current structure. So before migrating, you'll want to create enough separation that those concerns can move independently.

Choose a Migration Boundary Before Refactoring

Don't begin with:

Let's clean up the application.

Begin with:

What do we want to migrate first?

Suppose you decide the first capability will be Process Order. That gives your refactor a boundary.

Now you can map:

Input:
orderId

Business behavior:
load order
calculate adjustments
mark as processed

Side effects:
persist order
create payment
publish event
send email

Output:
processed order

This is much more useful than deciding to refactor:

src/services/

because a folder isn't necessarily a business boundary.

Migration works better when you can reason about capabilities.

For example:

Process Order
Cancel Order
Generate Invoice
Register Customer
Renew Subscription

Each can potentially become a migration unit.

Don't Refactor the Entire Application

Once you start identifying architectural problems, it becomes tempting to fix all of them.

You may notice:

circular dependencies
duplicated repositories
global configuration
large services
static helpers
direct database access
inconsistent error handling
mixed domain models

All of those may deserve attention, but the migration doesn't require all technical debt to disappear.

Suppose your target is the order-processing capability. A useful rule is to refactor only what prevents this capability from moving safely.

For example:

Problem:
Order processing calls MySQL directly.

Relevant?
Yes.

Problem:
The reporting module uses inconsistent date formatting.

Relevant?
Probably not.

Problem:
Order processing calls the payment SDK directly.

Relevant?
Yes.

Problem:
The admin UI contains duplicated CSS.

Relevant?
No.

This prevents preparation from becoming an open-ended cleanup project.

Legacy modernization needs scope discipline.

Separate Business Rules from Infrastructure

The most valuable structural change is often separating business behavior from technology-specific details.

Take this code:

async function processOrder(orderId: string) {
  const order = await mysqlOrders.find(orderId);

  if (order.customerType === "PREMIUM") {
    order.total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    order.total -= 500;
  }

  await mysqlOrders.update(order);

  await stripe.createPayment({
    orderId: order.id,
    amount: order.total,
  });
}

The pricing behavior itself doesn't need MySQL or Stripe.

You can extract it:

type Order = {
  id: string;
  total: number;
  customerType: "STANDARD" | "PREMIUM";
  country: string;
  paymentMethod: "CARD" | "TRANSFER";
};

function calculateOrderTotal(order: Order): number {
  let total = order.total;

  if (order.customerType === "PREMIUM") {
    total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    total -= 500;
  }

  return Math.max(total, 0);
}

Now:

pricing behavior

is no longer coupled to:

MySQL
Stripe

This doesn't require a complete domain-driven redesign. It's simply a useful separation.

The next migration step can replace infrastructure while leaving this behavior unchanged.

Introduce Seams Around Hard Dependencies

Legacy code often contains dependencies that can't easily be replaced in tests or migration code.

For example:

class OrderService {
  async process(orderId: string) {
    const client = new LegacyDatabaseClient();

    const order = await client.findOrder(orderId);

    // ...
  }
}

The database dependency is created inside the method.

That makes substitution difficult.

A small preparatory refactor can introduce a seam:

interface OrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

Then:

class OrderService {
  constructor(
    private readonly orders: OrderRepository
  ) {}

  async process(orderId: string) {
    const order = await this.orders.findById(orderId);

    if (!order) {
      throw new Error("Order not found");
    }

    // existing behavior
  }
}

Now the existing MySQL implementation can satisfy the interface:

class MySqlOrderRepository implements OrderRepository {
  async findById(id: string) {
    // existing MySQL behavior
  }

  async save(order: Order) {
    // existing MySQL behavior
  }
}

Later, the migration can introduce:

class PostgresOrderRepository implements OrderRepository {
  // new implementation
}

Notice what we didn't change: we didn't change the business behavior. We changed the replaceability of a dependency.

That's exactly the kind of refactoring that helps migration.

Isolate Side Effects from Decision Logic

Another useful separation is between:

deciding

and:

performing

Suppose cancellation currently looks like this:

async function cancelOrder(order: Order) {
  if (order.status === "SHIPPED") {
    throw new Error("Cannot cancel shipped order");
  }

  order.status = "CANCELLED";

  await orders.save(order);
  await inventory.release(order.id);
  await payment.refund(order.id);
  await audit.log("ORDER_CANCELLED", order.id);
}

There are two different responsibilities here.

The business decision:

Can this order be cancelled?
What should its new state be?

And the operational effects:

persist
release inventory
refund
audit

You could first extract the decision:

function cancelOrderState(order: Order): Order {
  if (order.status === "SHIPPED") {
    throw new Error("Cannot cancel shipped order");
  }

  return {
    ...order,
    status: "CANCELLED",
  };
}

Then orchestration remains:

async function cancelOrder(order: Order) {
  const cancelled = cancelOrderState(order);

  await orders.save(cancelled);
  await inventory.release(cancelled.id);
  await payment.refund(cancelled.id);
  await audit.log("ORDER_CANCELLED", cancelled.id);

  return cancelled;
}

The behavior is still the same, but now the state transition can be tested and migrated independently.

That matters if the target architecture changes how side effects are executed.

For example, the future version might use:

transactional outbox
event-driven workflow
queue
workflow engine

You don't need to introduce those mechanisms yet. You only need to stop the current decision logic from depending directly on them.

Put External Systems Behind Adapters

External SDKs often leak deeply into legacy code.

For example:

const result = await stripe.paymentIntents.create({
  amount: order.total,
  currency: "usd",
  metadata: {
    orderId: order.id,
  },
});

If dozens of application modules depend directly on the Stripe SDK, replacing or relocating payment processing becomes difficult.

Create an application-level boundary instead:

type PaymentRequest = {
  orderId: string;
  amount: number;
};

type PaymentResult = {
  paymentId: string;
};

interface PaymentGateway {
  charge(
    request: PaymentRequest
  ): Promise<PaymentResult>;
}

The Stripe adapter contains the provider-specific details:

class StripePaymentGateway implements PaymentGateway {
  async charge(
    request: PaymentRequest
  ): Promise<PaymentResult> {
    const result =
      await stripe.paymentIntents.create({
        amount: request.amount,
        currency: "usd",
        metadata: {
          orderId: request.orderId,
        },
      });

    return {
      paymentId: result.id,
    };
  }
}

The application now knows about:

PaymentGateway

instead of:

Stripe SDK

This is useful for migration because provider-specific code is localized.

The same pattern works for:

email providers
message brokers
cloud storage
ERP integrations
CRM APIs
identity providers
search engines

The adapter isn't valuable because interfaces are fashionable. It's valuable because it creates a boundary you can move.

Improve Dependency Direction Without Rebuilding Everything

Legacy systems often have dependency relationships such as:

business logic
    ↓
database SDK
    ↓
framework utilities

That makes infrastructure difficult to replace.

You don't necessarily need to implement full Clean Architecture. You only need to improve dependency direction where migration requires it.

For example:

Before:

OrderService
   ↓
MySQL

After:

OrderService
   ↓
OrderRepository
   ↑
MySqlOrderRepository

The application depends on an abstraction. The infrastructure implements it.

The same can happen with payments:

OrderService
   ↓
PaymentGateway
   ↑
StripePaymentGateway

and messaging:

OrderService
   ↓
OrderEvents
   ↑
KafkaOrderEvents

Now replacing infrastructure no longer requires rewriting the application service. That's the important outcome.

Extract a Cohesive Application Boundary

After several small refactors, the capability may start to look like this:

interface OrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

interface PaymentGateway {
  charge(request: {
    orderId: string;
    amount: number;
  }): Promise<void>;
}

interface OrderEvents {
  processed(order: Order): Promise<void>;
}

class ProcessOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
    private readonly events: OrderEvents
  ) {}

  async execute(orderId: string) {
    const order = await this.orders.findById(orderId);

    if (!order) {
      throw new Error("Order not found");
    }

    const total = calculateOrderTotal(order);

    const processed: Order = {
      ...order,
      total,
      status: "PROCESSED",
    };

    await this.orders.save(processed);

    await this.payments.charge({
      orderId: processed.id,
      amount: processed.total,
    });

    await this.events.processed(processed);

    return processed;
  }
}

This isn't necessarily the final architecture. That's important.

We aren't claiming:

This is how the application should look forever.

We're just saying:

This capability now has boundaries that make migration easier.

The infrastructure can change independently.

The business rules are testable. The orchestration is visible. And the external contracts are explicit.

That's enough to start considering migration.

Keep Behavioral Tests Running During the Refactor

This is where the characterization tests from the previous step become useful.

Suppose the original behavior was protected with:

it("preserves premium order processing behavior", async () => {
  const result = await processOrder("order-1");

  expect(result.total).toBe(9000);
  expect(result.status).toBe("PROCESSED");

  expect(payment.charge).toHaveBeenCalledWith({
    orderId: "order-1",
    amount: 9000,
  });

  expect(events.processed).toHaveBeenCalled();
});

Now you can change:

direct database access

into:

repository

and run the test.

Then change:

direct payment SDK

into:

payment adapter

and run the test.

Then extract:

pricing logic

and run the test.

The rhythm becomes:

small structural change
↓
test
↓
small structural change
↓
test
↓
small structural change
↓
test

This matters because structural refactoring is much easier to reason about when behavioral changes aren't happening at the same time.

If a test fails after one small change, the possible cause is narrow.

If a test fails after a two-week rewrite, the possible cause is almost everything.

How to Use AI During Structural Refactoring

AI can help a lot during this phase.

But the useful prompts are different from:

Refactor this application using Clean Architecture.

Instead, give the model a constrained transformation.

For example:

This service currently accesses MySQL directly.

I want to introduce an OrderRepository seam without
changing observable behavior.

Tasks:

1. identify every database operation used by this service,
2. propose the smallest repository interface needed,
3. move existing database calls behind an adapter,
4. preserve return values, errors, and call order where relevant,
5. do not change business rules,
6. do not introduce additional abstractions.

Explain every structural change before generating code.

That gives AI a much narrower job.

Another useful request is:

Compare the implementation before and after this refactor.

Identify any observable behavior that may have changed.

Check specifically:

- exceptions,
- return values,
- side effects,
- ordering of side effects,
- null handling,
- transaction boundaries,
- retry behavior.

Do not assume equivalence because the code looks similar.

This is where AI can be valuable as a second reviewer.

It can inspect differences faster than you can manually scan large changes. But the tests still provide stronger evidence.

Don't Ask AI to Design the Target Architecture Too Early

AI is very good at recognizing common architecture patterns. But that can also be dangerous.

Give a model a large legacy service and ask:

How should this be modernized?

and you may receive:

microservices
event-driven architecture
CQRS
repository pattern
domain events
message broker
API gateway
distributed cache

All of those are legitimate technologies or patterns, but none of them are automatically justified.

Before choosing a target architecture, you need constraints.

For example:

deployment frequency
team size
transactional requirements
latency
failure tolerance
data ownership
integration boundaries
operational maturity
traffic
cost
regulatory requirements

A monolith with good boundaries may be a better target than microservices. A synchronous workflow may be better than event-driven processing. And a database migration may not require changing the domain model.

Architecture should follow constraints, not pattern recognition.

Use AI to evaluate options. Don't let the presence of a familiar pattern become the reason to adopt it.

How to Know When a Capability Is Ready to Migrate

At some point, you have to stop refactoring. And that decision matters.

You don't need perfect code. A capability is usually much closer to migration-ready when you can answer these questions clearly.

Can I Describe its Inputs?

For example:

orderId
customer
request payload
event

Can I Describe its Outputs?

For example:

processed order
HTTP response
event
database change

Are its Important Business Rules Visible?

They don't have to be perfect, but you should know where they live.

Are External Dependencies Explicit?

For example:

OrderRepository
PaymentGateway
OrderEvents
EmailSender

Can Infrastructure Be Substituted?

If replacing MySQL requires changing pricing logic, the boundary is probably not ready.

Are Important Behaviors Protected?

You should have enough tests to detect accidental changes.

Do You Know the Side Effects?

For example:

persist order
create payment
publish event
send email

Are Major Unknowns Documented?

Some uncertainty may remain. But it shouldn't be invisible.

If you can answer those questions, you probably have enough structure to begin migrating that capability.

A Practical Pre-Migration Refactoring Workflow

Here's the workflow I would use.

1. Choose One Capability

Don't refactor the whole application.

Pick:

Process Order
Generate Invoice
Renew Subscription

2. Confirm Behavioral Protection

Before structural changes, make sure critical behavior has tests.

Capture:

outputs
state transitions
side effects
errors
contracts

3. Identify Migration Blockers

Look for coupling such as:

direct database access
provider SDKs
global state
framework-specific objects
static dependencies
shared mutable state

4. Extract Pure Business Logic Where Possible

Move calculations and decisions away from infrastructure.

For example:

calculate price
validate transition
choose status
calculate commission

5. Introduce Seams

Create minimal boundaries around:

database
payments
events
email
storage
external APIs

Don't create abstractions without a migration reason.

6. Localize Infrastructure

Move technology-specific behavior into adapters.

For example:

MySqlOrderRepository
StripePaymentGateway
KafkaOrderEvents
SendGridEmailSender

7. Make Orchestration Visible

Aim for a capability where the sequence is understandable:

load
↓
decide
↓
persist
↓
perform side effects
↓
return

8. Run Behavioral Tests After Every Step

Don't batch ten refactors together. Keep the changes small.

9. Compare Before and After

Check:

inputs
outputs
errors
side effects
data shapes
ordering
transactions

10. Stop When Migration Becomes Possible

Don't continue refactoring because the code could still be cleaner. It always could.

The objective is migration readiness.

What Not to Refactor Before Migration

There are several things I would usually avoid changing during this phase unless they directly block migration.

Naming Everywhere

You may dislike hundreds of old names. But renaming everything produces large diffs with little migration value.

Formatting the Entire Repository

Same problem. Noise makes behavioral changes harder to review.

Replacing Every Pattern

A legacy system may contain:

singletons
service locators
static utilities
large classes

Some may remain temporarily. Fix the ones crossing your migration boundary.

Rewriting Stable Algorithms

If an old calculation is ugly but protected and isolated, it may be safer to move it first and improve it later.

Fixing Every Discovered Bug

This one is especially important.

If you discover a bug while preparing a migration, record it. Then decide whether fixing it belongs in the same change.

Mixing:

structural refactor
+
behavioral correction
+
platform migration

makes failures much harder to understand.

Sometimes the right answer is:

preserve bug
migrate
fix bug intentionally afterward

That sounds uncomfortable. But accidental behavior changes during migration can be much more dangerous.

Refactoring Is Preparation, Not the Migration

It's easy for pre-migration refactoring to become an endless architecture project.

You start with:

We need to isolate the database.

Then:

We should redesign the domain model.

Then:

Maybe we should introduce events.

Then:

If we're doing that, maybe this should become a microservice.

Months later, nothing has migrated. The refactor has become the project.

That's a failure mode, too. The objective should remain concrete.

Before:

ProcessOrder
├── MySQL
├── pricing rules
├── Stripe
├── Kafka
├── email
└── framework internals

After:

ProcessOrder
├── OrderRepository
├── pricing rules
├── PaymentGateway
├── OrderEvents
└── EmailSender

That may be enough.

Now you have choices.

You can migrate:

MySQL → PostgreSQL

without redesigning pricing.

You can replace:

Stripe adapter

without changing order orchestration.

You can move:

ProcessOrder

into another runtime while preserving its contracts.

The refactor created options. That's the value.

Conclusion

Legacy migrations become risky when several types of change happen at once.

You change:

behavior
architecture
infrastructure
runtime
data
deployment

and then try to understand which change caused the failure.

A safer approach is to reduce that uncertainty before migration begins.

First understand the capability, then characterize its behavior, and then change its structure without intentionally changing what it does.

Create boundaries around dependencies. Separate business decisions from infrastructure. Localize external systems. Keep side effects visible. Run behavioral tests after every structural change. And stop refactoring when the capability becomes movable.

The sequence becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate

AI can make the refactoring phase dramatically faster.

It can identify dependencies, extract interfaces, move calls behind adapters, compare implementations, and review large diffs.

But faster refactoring doesn't remove the need for architectural judgment. It makes that judgment more important.

Because the goal isn't to produce the cleanest version of the legacy system. The goal is to create just enough structure to move it safely.

And once you can change the infrastructure without changing the behavior, migration stops looking like a rewrite.

It starts looking like a sequence of controlled changes.

]]> <![CDATA[ How to Build Characterization Tests Before Refactoring Legacy Code ]]> https://www.freecodecamp.org/news/characterization-tests-before-refactoring-legacy-code/ 6a958d8401db3f18f07d0b54 Mon, 31 Aug 2026 14:19:48 +0000 The first thing many engineers want to do when they inherit legacy code is improve it.

You find a function that's difficult to understand. Or you see duplicated logic, deeply nested conditions, database calls mixed with business rules, and dependencies that make testing almost impossible.

You know the code could be better, so you start cleaning it up.

Then something breaks. Not because the new implementation is obviously wrong. It breaks because the old implementation was doing something nobody knew it was doing.

That's one of the most common risks in legacy modernization.

Before changing code, you need a way to answer a simple question:

Did I preserve the behavior that already mattered?

That is where characterization tests become useful.

A characterization test doesn't begin by asking what the software should do. It begins by documenting what the software does today.

That distinction matters.

In a greenfield application, tests usually express intended behavior. But in a legacy application, you may first need tests that capture existing behavior so you can change the implementation without accidentally changing its observable results.

In this tutorial, I'll show you how to use characterization tests as a safety net before refactoring legacy code.

We'll look at how to:

  • identify behavior worth protecting,

  • choose useful test boundaries,

  • capture current outputs,

  • deal with side effects,

  • handle databases and external systems,

  • use AI to accelerate test discovery,

  • avoid freezing implementation details,

  • decide what not to characterize,

  • and turn characterization tests into a foundation for safer refactoring.

The examples use TypeScript and Vitest, but the approach applies to most languages and testing frameworks.

The goal isn't to preserve every line of legacy behavior forever. The goal is to make behavior visible before you start changing the code that produces it.

Prerequisites

You should be comfortable with:

  • TypeScript or a similar programming language

  • unit and integration testing

  • dependency injection

  • mocks and test doubles

  • basic refactoring techniques

  • reading an unfamiliar codebase

It also helps if you've already mapped the capability you want to change.

Before writing characterization tests, you should have some idea of:

  • where the behavior starts

  • what state it changes

  • which external systems it touches

  • which outputs may be consumed elsewhere

Table of Contents

What Characterization Tests Actually Protect

Suppose you inherit this function:

type Customer = {
  id: string;
  type: "STANDARD" | "PREMIUM";
};

type Order = {
  id: string;
  customer: Customer;
  subtotal: number;
  country: string;
  paymentMethod: "CARD" | "TRANSFER";
};

async function processOrder(order: Order) {
  let total = order.subtotal;

  if (order.customer.type === "PREMIUM") {
    total = total * 0.9;
  }

  if (order.country === "AR" && order.paymentMethod === "TRANSFER") {
    total = total - 500;
  }

  if (total < 0) {
    total = 0;
  }

  await ordersRepository.save({
    ...order,
    total,
    status: "PROCESSED",
  });

  await eventBus.publish("order.processed", {
    orderId: order.id,
    total,
  });

  return total;
}

There are several things you may want to refactor here.

For example, the pricing rules could move to another module. Persistence could be isolated. The event publisher could sit behind an interface. And the function could return an object rather than a primitive.

Those may all be good decisions, but before making them, you should ask: What behavior currently matters?

For this function, observable behavior includes at least:

  • premium customers receive a 10% discount

  • Argentine transfers receive another adjustment

  • totals can't become negative

  • the order is persisted with a specific status

  • an event is published

  • the event contains the calculated total

  • the function returns that total

A characterization test gives you a baseline for those behaviors.

For example:

import { describe, expect, it, vi } from "vitest";

describe("processOrder", () => {
  it("applies the existing premium customer behavior", async () => {
    const save = vi.spyOn(ordersRepository, "save");
    const publish = vi.spyOn(eventBus, "publish");

    const order: Order = {
      id: "order-1",
      customer: {
        id: "customer-1",
        type: "PREMIUM",
      },
      subtotal: 10000,
      country: "US",
      paymentMethod: "CARD",
    };

    const result = await processOrder(order);

    expect(result).toBe(9000);

    expect(save).toHaveBeenCalledWith(
      expect.objectContaining({
        id: "order-1",
        total: 9000,
        status: "PROCESSED",
      })
    );

    expect(publish).toHaveBeenCalledWith("order.processed", {
      orderId: "order-1",
      total: 9000,
    });
  });
});

This test isn't saying that a 10% discount is the best pricing model.

It's saying:

This is what the system currently does.

That's the contract you need to understand before changing it.

Start with Behavior, Not Implementation

A common mistake is to write tests around the structure you're planning to create.

Suppose you want to refactor the previous code into:

OrderProcessor
PricingPolicy
OrdersRepository
OrderEventPublisher

You may be tempted to write tests for those future classes first.

But those classes don't describe the existing system. They describe your proposed design.

Characterization tests should begin at the current observable boundary.

Instead of asking:

How should PricingPolicy work?

ask:

Given this input, what does processOrder() currently produce?

That difference helps prevent your new architecture from redefining behavior accidentally.

The sequence should be:

Observe existing behavior
↓
Capture it
↓
Refactor implementation
↓
Run characterization tests
↓
Verify behavior remains stable

Not:

Design new architecture
↓
Write tests for new architecture
↓
Assume it matches the old system

The second workflow tests your design. The first protects the migration.

Choose One Capability Before Writing Tests

Don't start by trying to characterize an entire legacy application. Instead, pick one business capability.

For example:

Approve Order
Generate Invoice
Renew Subscription
Register Customer
Calculate Commission
Cancel Reservation

Then trace that capability through the system.

Suppose you choose:

Generate Invoice

You discover this path:

POST /orders/:id/invoice
        ↓
InvoiceController.generate()
        ↓
InvoiceService.generate()
        ↓
TaxCalculator.calculate()
        ↓
InvoiceRepository.save()
        ↓
PdfGenerator.create()
        ↓
EmailService.send()

That becomes the scope of your investigation.

Now ask: Which behaviors matter if I refactor this capability?

Perhaps:

tax calculation
invoice numbering
database state
PDF fields
email recipient
email attachment
error behavior

Those are candidates for characterization.

This is more useful than trying to increase test coverage across the repository indiscriminately.

Coverage isn't the goal. Behavioral confidence is.

Find the Smallest Useful Test Boundary

Characterization tests can exist at different levels.

You might test:

function
service
module
API endpoint
background job
complete workflow

The right boundary is usually the smallest one that still captures meaningful behavior.

Suppose the logic you want to refactor lives inside:

class InvoiceService {
  async generate(orderId: string) {
    // 300 lines of legacy behavior
  }
}

If generate() coordinates tax calculation, persistence, numbering, and external calls, testing a small internal helper may not protect enough behavior.

Testing the whole production stack may be too slow and difficult.

A service-level characterization test may be the useful compromise.

For example:

describe("InvoiceService.generate", () => {
  it("preserves the existing invoice calculation", async () => {
    const service = createInvoiceService();

    const invoice = await service.generate("order-123");

    expect(invoice.subtotal).toBe(10000);
    expect(invoice.tax).toBe(2100);
    expect(invoice.total).toBe(12100);
  });
});

You don't want to ask what's the smallest unit you can test. You want to ask what's the smallest boundary that gives you confidence during this refactor.

Those aren't always the same thing.

Capture Existing Behavior Before Improving It

Legacy code often contains behavior that looks suspicious.

Consider:

function calculateDiscount(amount: number) {
  if (amount > 10000) {
    return amount * 0.15;
  }

  if (amount > 5000) {
    return amount * 0.1;
  }

  return 0;
}

You run a few examples and discover:

5000  -> 0
5001  -> 500.1
10000 -> 1000
10001 -> 1500.15

You might think:

5000 should probably receive the 10% discount.

Maybe. But that's not what the current code does.

A characterization test could record:

describe("calculateDiscount", () => {
  it.each([
    [5000, 0],
    [5001, 500.1],
    [10000, 1000],
    [10001, 1500.15],
  ])(
    "returns the existing discount for amount %d",
    (amount, expected) => {
      expect(calculateDiscount(amount)).toBe(expected);
    }
  );
});

This creates a behavioral boundary around the existing implementation.

Later, if the business confirms that 5000 should receive a discount, you can intentionally change:

if (amount > 5000)

to:

if (amount >= 5000)

and update the relevant test.

The important part is that the change becomes explicit.

Without the test, it could happen accidentally during an unrelated refactor.

Characterize Edge Cases You Don't Yet Understand

The obvious cases aren't always the risky ones. Legacy systems often fail at boundaries.

Look for values such as:

0
-1
null
empty string
maximum value
minimum value
exact threshold values
unknown status
duplicate identifiers
missing related records

Suppose you find:

function normalizeBalance(balance?: number) {
  if (!balance) {
    return 0;
  }

  return Math.round(balance * 100) / 100;
}

That means:

undefined -> 0
0         -> 0

But also potentially:

NaN -> 0

because NaN is falsy.

Is that intentional? You may not know yet.

You can characterize it:

describe("normalizeBalance", () => {
  it("returns zero for undefined", () => {
    expect(normalizeBalance(undefined)).toBe(0);
  });

  it("returns zero for zero", () => {
    expect(normalizeBalance(0)).toBe(0);
  });

  it("returns zero for NaN in the current implementation", () => {
    expect(normalizeBalance(Number.NaN)).toBe(0);
  });
});

The name matters.

Notice that I wrote:

in the current implementation

I'm not pretending that behavior is correct. I'm just documenting it.

That distinction becomes important when a test describes questionable behavior.

Test Side Effects, Not Just Return Values

A return value is only one kind of behavior.

Legacy functions frequently produce side effects.

Consider:

async function cancelOrder(order: Order) {
  order.status = "CANCELLED";

  await orders.save(order);
  await inventory.release(order.id);
  await audit.log("ORDER_CANCELLED", order.id);

  return order;
}

A weak characterization test might only check:

expect(result.status).toBe("CANCELLED");

But a refactor could still accidentally remove:

inventory.release()
audit.log()

and the test would continue passing.

A stronger characterization test captures observable side effects:

it("preserves cancellation side effects", async () => {
  const save = vi.spyOn(orders, "save");
  const release = vi.spyOn(inventory, "release");
  const log = vi.spyOn(audit, "log");

  const order = {
    id: "order-1",
    status: "APPROVED",
  } as Order;

  await cancelOrder(order);

  expect(save).toHaveBeenCalled();

  expect(release).toHaveBeenCalledWith("order-1");

  expect(log).toHaveBeenCalledWith(
    "ORDER_CANCELLED",
    "order-1"
  );
});

This doesn't mean every internal call deserves an assertion.

The question is whether the call produces observable behavior that matters outside the implementation.

How to Characterize Code That Depends on a Database

Database-heavy legacy code can be difficult to test.

Suppose you have:

async function activateCustomer(customerId: string) {
  const customer = await db.customers.findById(customerId);

  if (!customer) {
    throw new Error("Customer not found");
  }

  await db.customers.update(customerId, {
    status: "ACTIVE",
    activatedAt: new Date(),
  });

  return db.customers.findById(customerId);
}

You have several options.

Use an Integration Test

If the database behavior itself matters, run against a disposable test database.

For example:

it("activates an existing customer", async () => {
  await seedCustomer({
    id: "customer-1",
    status: "PENDING",
  });

  const result = await activateCustomer("customer-1");

  expect(result?.status).toBe("ACTIVE");
  expect(result?.activatedAt).toBeTruthy();
});

This gives high confidence, but the test may be slower.

Introduce a Seam

If database access makes testing impractical, you may need a very small structural change before characterization.

For example:

type CustomerRepository = {
  findById(id: string): Promise<Customer | null>;
  update(
    id: string,
    data: Partial<Customer>
  ): Promise<void>;
};

Then:

async function activateCustomer(
  customerId: string,
  customers: CustomerRepository
) {
  // existing behavior
}

This is a useful concept from legacy-code work: create a seam, a place where behavior can be observed or replaced without rewriting the system.

The key is to keep this preparatory change mechanical.

Don't redesign the business logic while creating the test boundary.

First make it testable. Then characterize it. Then refactor.

How to Handle External Services

Legacy code frequently talks directly to:

payment providers
email services
ERPs
CRMs
message brokers
cloud storage
third-party APIs

You usually don't want characterization tests repeatedly calling those systems.

Instead, capture the interaction at the boundary.

Suppose:

async function chargeOrder(order: Order) {
  const response = await stripe.charge({
    amount: order.total,
    currency: "usd",
    customerId: order.customerId,
  });

  await orders.markPaid(order.id, response.id);

  return response.id;
}

You can characterize the request:

it("sends the existing payment payload", async () => {
  const charge = vi
    .spyOn(stripe, "charge")
    .mockResolvedValue({
      id: "payment-123",
    });

  const markPaid = vi.spyOn(orders, "markPaid");

  const order = {
    id: "order-1",
    total: 5000,
    customerId: "customer-1",
  } as Order;

  await chargeOrder(order);

  expect(charge).toHaveBeenCalledWith({
    amount: 5000,
    currency: "usd",
    customerId: "customer-1",
  });

  expect(markPaid).toHaveBeenCalledWith(
    "order-1",
    "payment-123"
  );
});

That protects the external contract without hitting the external system.

But be careful. If the provider behavior itself matters, mocks alone may not be enough.

You might also need:

  • provider sandbox tests

  • contract tests

  • integration tests

  • schema validation

Characterization testing doesn't eliminate the need for those layers.

How to Use AI to Discover Characterization Tests

AI is particularly useful when you are staring at a large legacy function and trying to understand what deserves a test.

Suppose you have a 400-line service.

Instead of asking:

Write unit tests for this class.

use a more investigative prompt:

Analyze this class without changing it.

Identify observable behaviors that could change during refactoring.

Group them into:

1. returned values,
2. state changes,
3. persistence effects,
4. external calls,
5. emitted events,
6. exceptions,
7. boundary conditions.

For every proposed characterization test:

- reference the relevant source code,
- explain what behavior the test would protect,
- distinguish observed behavior from inferred behavior.

Do not invent expected values.

That final instruction matters: you want AI to help identify what to observe. You don't want it inventing what the software should do.

Another useful prompt is:

Review the existing test suite for this capability.

Compare the behaviors covered by tests with the
observable behaviors in the implementation.

List behavior that appears unprotected.

Do not generate tests yet.

This is often more valuable than immediately asking for test code.

First identify the gaps, and then decide which gaps matter.

Don't Let AI Invent Expected Behavior

This is probably the most important rule when combining AI with characterization testing, and it's worth talking a bit more about.

Suppose AI reads:

if (customer.age > 65) {
  discount = 0.2;
}

It may generate:

expect(calculateDiscount(65)).toBe(0.2);

because it assumes the intended business rule is:

Customers aged 65 or older receive a discount.

But that's not what the code says.

The existing behavior is:

65 -> no discount
66 -> discount

The expected values in characterization tests should come from evidence.

Useful evidence includes:

  • running the current system

  • existing tests

  • fixtures

  • production-safe observations

  • documented examples

  • database state

  • historical behavior

Don't derive expectations solely from what seems reasonable.

A better AI instruction is:

For each candidate test, tell me how I can obtain
the expected result from the current implementation.

Do not propose the expected result yourself unless it
can be directly derived from executable behavior
or an existing test.

This turns AI into an assistant for experiment design rather than an authority on business rules.

Avoid Testing Implementation Details

Characterization tests can become harmful if they freeze the current code structure.

Suppose the implementation is:

async function processOrder(order: Order) {
  validateOrder(order);
  calculatePrice(order);
  reserveInventory(order);
  saveOrder(order);
}

A brittle test might assert:

expect(validateOrder).toHaveBeenCalledBefore(calculatePrice);
expect(calculatePrice).toHaveBeenCalledBefore(reserveInventory);
expect(reserveInventory).toHaveBeenCalledBefore(saveOrder);

Maybe that order matters. Maybe it doesn't.

If consumers only care about:

correct total
inventory reserved
order persisted

then asserting the exact sequence unnecessarily constrains the refactor.

Prefer protecting externally meaningful behavior.

For example:

expect(savedOrder.total).toBe(9000);
expect(inventory.reserve).toHaveBeenCalledWith(
  "product-1",
  2
);
expect(repository.save).toHaveBeenCalled();

Characterization tests should create a safety net. They shouldn't turn the legacy implementation into a specification of every internal decision.

When a Characterization Test Reveals a Bug

Eventually you'll encounter behavior that appears clearly wrong.

For example:

function calculateFee(amount: number) {
  if (amount === 0) {
    return 100;
  }

  return amount * 0.02;
}

You confirm that zero-value transactions are charged a fixed fee. Everyone agrees this looks suspicious.

What should the characterization test do?

First, separate two questions:

  1. What does the system do today?

  2. What should the system do?

The characterization test answers the first.

it("currently charges 100 for a zero-value transaction", () => {
  expect(calculateFee(0)).toBe(100);
});

Then investigate whether this is intentional business behavior, a historical workaround, or an actual defect.

If the business confirms it is a bug, create a separate change.

For example:

it("does not charge a fee for a zero-value transaction", () => {
  expect(calculateFee(0)).toBe(0);
});

Then modify the production code.

This may sound overly formal for a small condition. But it creates a clean distinction between:

behavior discovered during refactoring

and:

behavior intentionally changed

That distinction becomes extremely valuable in large migrations.

How Much Behavior Should You Characterize

You don't need to characterize everything. Trying to preserve every observed detail can create another form of paralysis.

Prioritize behavior with high change risk or high business impact.

I usually look first at:

  • financial calculations

  • state transitions

  • authentication and authorization

  • external contracts

  • queue and event payloads

  • data transformations

  • retry behavior

  • idempotency

  • regulatory rules

  • critical error handling

You may care less about:

  • internal helper naming

  • private method structure

  • log wording that nobody consumes

  • temporary object shapes

  • implementation-specific call sequences

A useful question is: If this behavior changed during refactoring, could somebody outside this function notice?

If the answer is yes, it's probably worth considering.

Use Characterization Tests During the Refactor

Once the characterization suite exists, keep the refactor small.

Suppose you begin with:

async function processOrder(order: Order) {
  // validation
  // pricing
  // inventory
  // persistence
  // event publishing
}

You might first extract pricing:

function calculateOrderTotal(order: Order) {
  let total = order.subtotal;

  if (order.customer.type === "PREMIUM") {
    total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    total -= 500;
  }

  return Math.max(total, 0);
}

Run the characterization suite. If everything still passes, continue.

Next isolate inventory and run it again.

Then persistence. Run it again.

This gives you a migration rhythm:

small structural change
↓
run tests
↓
observe
↓
continue

If something fails, the search space is small.

Compare that with rewriting 2,000 lines and then discovering 47 broken tests.

Small changes turn failures into useful feedback, while Large changes turn failures into archaeology.

Again.

A Practical Characterization Testing Workflow

Here is the workflow I would use on an unfamiliar legacy capability.

1. Map the Capability

Identify:

entry point
business logic
state changes
side effects
external contracts
outputs

Don't refactor yet.

2. Find Existing Tests

Search for tests that already describe the capability.

Look for:

happy paths
boundary cases
errors
historical bugs
integration behavior

Don't duplicate useful tests unnecessarily.

3. List Observable Behaviors

Create a table such as:

Behavior Evidence Protected?
Premium discount Code + production example No
Order event Code Yes
Transfer adjustment Code No
Negative total clamp Code No
Save status Existing integration test Yes

Now you know where the risk is.

4. Pick the Test Boundary

Decide whether the useful boundary is:

function
service
module
endpoint
job
workflow

Choose based on confidence, not test ideology.

5. Capture Current Behavior

Run the existing system.

Use real observable outputs when possible.

Don't guess expectations.

6. Add Critical Edge Cases

Test:

thresholds
empty values
nulls
errors
duplicate operations
retry scenarios

especially around logic you intend to change.

7. Capture Side Effects

Protect meaningful:

writes
events
messages
external calls
state transitions

not only function return values.

8. Mark Uncertain Behavior

Use test names or documentation that clearly distinguishes:

confirmed business rule

from:

current observed behavior

9. Refactor Incrementally

Make one structural change.

Run the suite.

Repeat.

10. Replace Characterization with Intent Where Appropriate

As understanding improves, some characterization tests can evolve into true specification tests.

Instead of:

currently returns 0 for this input

you may eventually be able to say:

does not apply a discount below the premium threshold

That transition is useful. It means the system is becoming understood rather than merely preserved.

What Characterization Tests Can't Tell You

Characterization tests are powerful, but they have an important limitation.

They tell you what happened for the cases you observed. They don't automatically tell you why.

Suppose the test says:

Argentine transfer orders receive a 500-unit adjustment.

The test can protect that behavior.

It can't tell you whether the adjustment exists because of:

  • a tax rule

  • a banking fee

  • an old promotion

  • a customer-specific workaround

  • a bug nobody removed

For that, you still need other evidence:

  • documentation

  • Git history

  • production telemetry

  • domain experts

  • incident records

  • external system contracts

This is why characterization testing belongs after codebase understanding, not instead of it.

You first discover the behavior. Then you protect it. Then you continue investigating what it means.

Characterization Tests Are Temporary Knowledge Infrastructure

There's another way I think about these tests.

Legacy systems contain knowledge that's often trapped inside implementation details. A characterization test moves some of that knowledge into an executable form.

Before:

Nobody knows what changing this condition will break.

After:

Changing this condition causes these four observable behaviors to change.

That's already progress.

The test suite becomes part of your understanding of the system. It creates a bridge between:

what the code currently does

and:

what we eventually want the system to do

You don't have to keep every characterization test forever.

Some will become proper specification tests.

Some will disappear when obsolete behavior is intentionally removed.

Some will remain as regression tests.

Their first job is simpler: make change safer while understanding is still incomplete.

Conclusion

AI makes refactoring legacy code faster.

It can explain functions, generate candidate abstractions, extract interfaces, suggest module boundaries, and rewrite large sections of code in seconds.

That makes characterization testing more important, not less.

When the cost of producing a new implementation decreases, the risk shifts toward verifying that the new implementation still preserves the behavior that matters.

Before asking:

How should I refactor this?

ask:

What does this do today?

Then:

Which of those behaviors matter?

Then:

How can I prove they still work after the change?

That is what characterization tests give you.

They don't tell you that legacy behavior is correct. They give you evidence that it exists.

And once that evidence is executable, you can refactor with much more confidence.

The sequence becomes:

Understand
↓
Characterize
↓
Refactor
↓
Verify

AI can accelerate every step in that workflow. But the engineering judgment remains in deciding what behavior deserves to survive, what behavior should change, and when you have enough evidence to safely make that distinction.

]]> <![CDATA[ How to Understand a Legacy Codebase Using AI Before Changing it ]]> https://www.freecodecamp.org/news/understand-a-legacy-codebase-with-ai/ 6a888892029633fd14697876 Fri, 21 Aug 2026 17:19:14 +0000 The first thing many engineers want to do when they inherit a legacy codebase is change it. And I understand the impulse.

You open a class that's 1,500 lines long. There are database calls mixed with business rules, configuration values scattered across the repository, methods nobody wants to touch, and comments that refer to systems that disappeared years ago.

Then an AI coding assistant offers to explain the whole thing.

So you ask:

Refactor this class.

But that's usually too early.

One of the lessons I've learned from working with legacy systems is that code can be ugly and still contain important knowledge.

A strange condition may encode a business exception. A duplicated calculation may exist because two processes that look identical aren't actually identical. A database column with a terrible name may still be part of an external contract.

And a method nobody understands may be the only thing preventing a production incident that happened eight years ago from happening again.

AI makes it much easier to read unfamiliar software, and that's valuable. But it also makes it much easier to change software before you understand it.

In this tutorial, I'll show you how to use AI for something I believe should happen before refactoring or migration: codebase archaeology.

You'll learn how to use AI to help you:

  • map a repository,

  • identify entry points,

  • trace dependencies,

  • separate business rules from infrastructure,

  • find hidden side effects,

  • inspect data flow,

  • discover implicit contracts,

  • detect duplicated behavior,

  • build a dependency map,

  • identify areas of uncertainty,

  • and turn those findings into a modernization plan.

The examples use TypeScript, but the process works with most languages and stacks.

The goal isn't to ask AI what the code means and trust the answer. The goal is to use AI to reduce the amount of time you spend looking for the right questions.

Prerequisites

You should be comfortable with:

  • reading an existing codebase

  • TypeScript or a similar object-oriented language

  • basic software architecture

  • dependency injection

  • unit and integration testing

  • using an AI coding assistant that can inspect repository files

You don't need a specific AI provider, as the workflow matters more than the model.

Table of Contents

Why Understanding Has to Come Before Refactoring

Legacy code often creates a false sense of urgency.

You see something obviously coupled or duplicated and immediately want to clean it up.

Consider this function:

async function approveOrder(order: Order) {
  if (order.total > 10000 && !order.customer.verified) {
    throw new Error("Manual verification required");
  }

  if (
    order.customer.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    order.status = "PENDING";
  } else {
    order.status = "APPROVED";
  }

  await orders.save(order);

  if (order.status === "APPROVED") {
    await billing.createInvoice(order);
  }

  await audit.log({
    action: "ORDER_APPROVAL",
    orderId: order.id,
    status: order.status,
  });

  return order;
}

At first glance, there are several clear refactoring opportunities:

  • You could extract validation.

  • You could isolate status calculation.

  • You could move billing behind an interface.

  • You could create an approval policy.

All of those ideas may be reasonable, but there are questions you should answer first:

  • Why is 10000 important?

  • Why does an Argentine bank transfer remain pending?

  • Does invoice creation have to happen after persistence?

  • Is ORDER_APPROVAL consumed by another system?

  • Can orders transition from PENDING to APPROVED somewhere else?

  • Does anything depend on the exact exception message?

You can't answer those questions from syntax alone.

That's where understanding begins.

Instead of asking your AI tool:

Refactor this function using clean architecture.

start with:

Analyze this function without changing it.

Identify:

1. explicit business rules,
2. likely business rules that need confirmation,
3. side effects,
4. external dependencies,
5. state transitions,
6. magic values,
7. assumptions that cannot be proven from this file alone.

Do not propose a refactor yet.

That last line is important: Do not propose a refactor yet.

You want the model in investigation mode, not solution mode.

How to Start with the Repository, Not the Classes

When I approach an unfamiliar legacy system, I don't start by reading every file. I start by trying to understand the shape of the application.

A repository already contains architectural clues.

Look for directories such as:

src/
controllers/
services/
repositories/
models/
jobs/
workers/
scripts/
migrations/
config/
integrations/
tests/

But don't assume the directory names describe the real architecture.

A directory called services can contain business logic, infrastructure, orchestration, and random utility functions.

A directory called models might contain database entities rather than domain models.

A folder called utils can hide half the application's business logic.

Use the structure as evidence, not truth.

A useful first AI request is:

Inspect the repository structure.

Do not analyze individual implementation details yet.

Identify:

- application entry points,
- major modules,
- database technologies,
- external integrations,
- background processing,
- scheduled tasks,
- authentication mechanisms,
- configuration sources,
- tests,
- likely architectural boundaries.

For each conclusion, reference the files or directories
that support it.

Mark anything uncertain explicitly.

The requirement to reference files matters. Without it, AI can give you a perfectly reasonable architecture that doesn't actually exist.

You want something closer to:

HTTP API
Evidence:
- src/server.ts
- src/routes/orders.ts
- src/routes/customers.ts

Background processing
Evidence:
- src/workers/paymentWorker.ts
- src/queues/index.ts

Scheduled jobs
Evidence:
- src/jobs/reconcileInvoices.ts
- src/cron.ts

Now you have a map you can verify.

How to Find the Real Entry Points

Web applications often have an obvious HTTP entry point. But legacy systems frequently have several more.

A business operation may begin from:

  • an API request,

  • a scheduled job,

  • a queue consumer,

  • a database trigger,

  • a CLI script,

  • a file import,

  • an email handler,

  • a webhook,

  • or another application calling the database directly.

If you only analyze controllers, you may miss half the system.

Suppose you search for order creation and find:

POST /orders

It would be easy to assume that all orders enter through that endpoint.

Then you discover:

jobs/importMarketplaceOrders.ts
workers/retryFailedOrders.ts
scripts/migratePendingOrders.ts
integrations/shopify/webhook.ts

Now the same business object has four additional entry paths.

This changes how you think about refactoring.

Ask AI:

Find every location that can create, modify,
approve, cancel, or persist an Order.

Include:

- HTTP endpoints,
- background workers,
- scheduled jobs,
- scripts,
- imports,
- webhooks,
- direct repository calls.

Group the results by operation.

For every result, include the file path and
the relevant function or class.

Then verify those results with repository search.

For example:

rg "orders\.save|orders\.insert|createOrder|approveOrder" src

AI should accelerate search, not replace it.

How to Trace a Business Capability Through the Codebase

Understanding individual files isn't enough.

What usually matters is understanding a business capability.

For example:

Create an order.

That capability may travel through several layers:

HTTP Request
     ↓
Controller
     ↓
Application Service
     ↓
Pricing
     ↓
Inventory
     ↓
Persistence
     ↓
Payment
     ↓
Notification

The code may not be organized that cleanly, and that's precisely why tracing the capability is useful.

Choose one real workflow and ask:

Trace the "Create Order" capability from its entry point
until all observable side effects are complete.

For each step, show:

- file,
- function or class,
- input,
- output,
- state change,
- external call,
- error behavior.

Do not summarize multiple steps into one.

You want a sequence that you can inspect.

For example:

1. POST /orders
   src/routes/orders.ts

2. OrdersController.create()
   src/controllers/OrdersController.ts

3. OrderService.create()
   src/services/OrderService.ts

4. calculatePrice()
   src/services/pricing.ts

5. inventory.reserve()
   src/integrations/inventory.ts

6. ordersRepository.save()
   src/repositories/orders.ts

7. paymentQueue.publish()
   src/queues/payment.ts

This becomes far more useful than a generic explanation of the architecture.

Now you can ask questions such as:

  • Where does the transaction actually begin?

  • What happens if payment publishing fails?

  • Is inventory reservation reversible?

  • Can the order be saved twice?

  • Which steps are synchronous?

  • Which failures are retried?

Those are modernization questions.

How to Separate Business Rules from Infrastructure

One of the most useful things you can do during codebase archaeology is identify where business behavior lives.

Legacy applications frequently mix it with infrastructure.

Consider:

async function saveCustomer(customer: Customer) {
  if (
    customer.type === "ENTERPRISE" &&
    customer.creditLimit < 50000
  ) {
    throw new Error("Invalid enterprise credit limit");
  }

  const connection = await mysql.getConnection();

  await connection.query(
    "INSERT INTO customers (...) VALUES (...)",
    [...]
  );

  await redis.del(`customer:${customer.id}`);

  await eventBus.publish(
    "customer.updated",
    customer
  );
}

There's at least one business rule:

Enterprise customers must have a credit limit >= 50000.

And several infrastructure concerns:

MySQL
Redis
Event bus

Ask AI to classify the code:

Classify each responsibility in this function as one of:

- business rule,
- application orchestration,
- persistence,
- caching,
- messaging,
- logging,
- validation,
- unknown.

Explain why.

Do not move or rewrite any code.

The unknown category is useful. You don't want the model to force every line into a clean architectural theory.

Some code really is ambiguous until you inspect more context.

How to Find Hidden Side Effects

Side effects are one of the biggest sources of migration risk.

A function called:

updateCustomer()

may do much more than update a customer.

It may:

  • write to the database

  • invalidate cache

  • emit an event

  • send an email

  • update analytics

  • write an audit record

  • schedule another job

If you refactor the function and preserve only its return value, you can break production behavior without any compiler error.

A useful investigation prompt is:

List every observable side effect produced directly
or indirectly by this function.

For each one, identify:

- the side effect,
- where it happens,
- whether it is synchronous or asynchronous,
- whether failure propagates,
- whether it appears retryable,
- whether it is idempotent,
- whether it can be safely repeated.

Mark uncertain answers as unknown.

That last property, idempotency, matters a lot.

Suppose a worker does this:

await chargeCard(order);
await markOrderAsPaid(order);

If the worker crashes between those two lines and retries, what happens? You may charge the customer twice. And that's not visible from the function name.

Understanding retry semantics is part of understanding the codebase.

How to Discover Implicit Contracts

Not every contract is declared with an interface. Legacy applications contain many implicit contracts.

For example:

return {
  status: "ok",
  value: customer.balance.toFixed(2),
};

Some external consumer may depend on:

{
  "status": "ok",
  "value": "100.00"
}

Changing value from a string to a number can look like an improvement:

{
  "status": "ok",
  "value": 100
}

It can also break a client.

Look for contracts in:

  • API responses,

  • events,

  • database structures,

  • CSV exports,

  • filenames,

  • environment variables,

  • error messages,

  • queue payloads,

  • and webhook bodies.

Ask:

Identify outputs from this module that could be consumed
outside the module.

Include:

- HTTP responses,
- emitted events,
- queue messages,
- files,
- database records,
- exceptions,
- logs used for automated processing.

For each output, explain what evidence suggests that it
may be an external or implicit contract.

The wording matters:

what evidence suggests

not:

tell me which contracts exist

because you may not be able to prove the consumer from the current repository.

How to Use AI to Find Duplicated Business Rules

Duplicated code is easy to detect. Duplicated business meaning is harder.

You may find:

if (customer.type === "PREMIUM") {
  discount = total * 0.1;
}

in one module.

And elsewhere:

if (account.plan === "GOLD") {
  price = price * 0.9;
}

Those might represent the same business rule, or they might not.

AI is useful for identifying candidates.

Ask:

Search the repository for business rules related to
customer discounts.

Group implementations that appear semantically related,
even if variable names differ.

For each group:

- list file locations,
- describe the apparent rule,
- highlight differences,
- do not assume the rules should be unified.

That final instruction is important.

Duplication is sometimes accidental.

Sometimes it represents two domains that evolved independently.

Don't let an AI assistant turn:

similar

into:

must be merged

without evidence.

How to Build a Lightweight Dependency Map

At some point, you need to understand which parts of the system depend on which others.

You don't need a perfect enterprise architecture diagram. A lightweight dependency map is enough to start.

For example:

Orders
 ├── Customers
 ├── Inventory
 ├── Payments
 ├── Notifications
 └── Database

Payments
 ├── Payment Provider
 ├── Audit
 └── Database

Ask AI to extract module-level dependencies:

Build a module dependency map from the repository.

Only include dependencies supported by imports,
constructor dependencies, explicit calls, or configuration.

Output:

Module A -> Module B

For each dependency, provide at least one source file
that demonstrates it.

Do not infer dependencies from names alone.

You can then compare the result with automated tools.

For JavaScript or TypeScript projects, dependency analysis tools can help you find:

  • circular dependencies

  • cross-module imports

  • high fan-in

  • high fan-out

AI is useful for explaining why those dependencies may matter. Static analysis is better at proving that they exist.

Use both.

How to Mark What You Still Do Not Understand

This is one of the most important parts of the process.

A useful system map doesn't only contain answers. It also contains uncertainty.

I like keeping an explicit list such as:

## Open Questions

- Why is the enterprise credit threshold 50,000?
- Is `ORDER_APPROVAL` consumed outside this repository?
- Can marketplace orders bypass inventory validation?
- Is `customer.balance` allowed to be negative?
- What process transitions PENDING orders to APPROVED?
- Is `legacy_customer_id` still used by another system?

You can ask AI to generate this list:

Based on everything analyzed so far, list the questions
that can't be answered safely from the repository.

Focus on questions that would matter during:

- refactoring,
- migration,
- schema changes,
- interface changes,
- removal of code.

Do not answer the questions.

I like this prompt because it does the opposite of what we normally ask AI to do. It asks the model to identify where it should not pretend to know.

A modernization plan should include those unknowns.

How to Validate AI Findings Against the System

AI-generated explanations can sound convincing even when they're incomplete. So every important finding should have another source of evidence.

I use a simple hierarchy.

If AI says a function is called only once, search for it.

rg "approveOrder" .

Tests

Tests often reveal assumptions that implementation code doesn't explain.

Look for:

expected errors
special values
boundary cases
fixture data
historical behavior

Database Schema

The schema may reveal key things like:

  • nullable fields

  • foreign keys

  • defaults

  • legacy columns

  • constraints

  • status values

Logs and Observability

Production telemetry can tell you whether a supposedly unused path is still active.

Version History

Git history can sometimes answer questions that source code can't.

For example:

git log -S "Manual verification required" --all

or:

git blame src/orders/approveOrder.ts

The commit that introduced a strange condition may contain the explanation.

This is an area where AI can help summarize history:

Review the commits that changed this function.

Build a timeline of behavior changes.

For each change, include:

- commit,
- date,
- behavior changed,
- stated reason if available.

Do not infer a reason if the commit history does not provide one.

That can save a surprising amount of time.

How to Turn Codebase Understanding into a Migration Plan

Once you understand one capability, you can begin making decisions. But not before.

Suppose your investigation produces this:

Create Order

Business rules:
- active customer required
- premium customers receive 10% discount
- inventory must be available

Side effects:
- order persisted
- inventory reserved
- payment queued
- confirmation email sent

External contracts:
- POST /orders response
- payment queue payload
- order.created event

Unknowns:
- retry semantics for inventory reservation
- whether event consumers require exact field names

Now you can decide what to protect.

For example:

Protect first:
- pricing behavior
- API response
- payment payload
- event schema

Then decide what can be refactored.

Candidate boundaries:
- pricing policy
- inventory gateway
- payment publisher
- notification service

Then decide what needs investigation.

Block migration until understood:
- inventory retry behavior
- event consumers

That's already a migration plan.

Notice what AI did not do: it didn't decide the target architecture.

It helped make the current architecture observable enough for you to make that decision.

A Practical Codebase Archaeology Workflow

If I had to reduce this process to something repeatable, I would use these steps.

1. Map the Repository

Identify:

  • entry points

  • modules

  • persistence

  • integrations

  • workers

  • jobs

  • tests

  • configuration

Don't refactor anything.

2. Choose One Capability

Pick something concrete:

Create Order
Approve Loan
Generate Invoice
Register Customer
Cancel Subscription

Avoid trying to understand the whole product at once.

3. Trace It End to End

Follow:

input
↓
business logic
↓
state changes
↓
external calls
↓
output

Record every file involved.

4. Extract Business Rules

Separate:

  • explicit rules

  • likely rules

  • infrastructure behavior

  • unknowns

5. Identify Side Effects

Find:

  • writes

  • messages

  • emails

  • jobs

  • cache changes

  • external calls

6. Discover Contracts

Look for:

  • APIs

  • event schemas

  • database assumptions

  • exported files

  • error behavior

7. Map Dependencies

Document:

module -> module

and identify coupling.

8. Record Unknowns

Don't hide uncertainty. Create an explicit list.

9. Verify

Use:

  • repository search

  • tests

  • schema

  • logs

  • Git history

  • production telemetry

10. Only Then Plan the Change

Decide:

  • what behavior must survive,

  • what code can disappear,

  • what boundaries should be introduced,

  • what needs tests,

  • and what can migrate first.

What I Would Not Ask AI to Do First

There are several prompts I avoid at the beginning of a legacy modernization project.

For example:

Rewrite this application using Clean Architecture.

or:

Convert this monolith into microservices.

or:

Modernize this entire repository.

or even:

Find all the bad code.

The problem isn't that AI can't produce useful output from those prompts. It can.

The problem is that those questions already contain a solution.

You're asking for:

Clean Architecture
Microservices
Rewrite
Bad code

before you've established what the system actually needs.

A better sequence is:

What exists?
↓
Why does it exist?
↓
What behavior matters?
↓
What is uncertain?
↓
What should change?

That sequence is slower for the first hour, but it's usually much faster for the rest of the project.

The Most Useful AI Output Is Sometimes a Question

There's a tendency to evaluate AI coding tools by how much code they generate.

For legacy systems, I think that misses part of their value.

One of the most useful outputs can be:

I cannot determine why this condition exists from the available code.

Or:

This event appears to have no consumer in the current repository, but external consumers cannot be ruled out.

Or:

These two discount calculations look similar, but their behavior differs for zero-value orders.

Those are useful findings that tell an engineer where to investigate.

A confident but incorrect answer is much more dangerous.

When working with legacy systems, uncertainty is information. Treat it that way.

Conclusion

AI makes unfamiliar codebases much easier to explore.

You can use it to summarize modules, trace execution paths, extract candidate business rules, find side effects, compare implementations, analyze Git history, and build dependency maps.

That can remove a large amount of mechanical investigation work.

But understanding a system isn't the same as generating an explanation of it. Legacy applications contain context that may exist outside the source code:

  • production behavior,

  • old incidents,

  • external consumers,

  • business exceptions,

  • undocumented integrations,

  • and organizational history.

AI can help you find evidence. It can't manufacture missing history.

That's why I prefer to use it as an investigator before I use it as a transformer.

Start with:

What does this system actually do?

Then ask:

What do I still not understand?

Only after that should you ask:

What should I change?

The faster AI lets you modify software, the more important that sequence becomes.

Because changing code you understand is engineering. But changing code you don't understand is experimentation.

And production is usually the most expensive place to run that experiment.

]]> <![CDATA[ How to Modernize a Legacy Application with AI Without Turning It Into a Rewrite ]]> https://www.freecodecamp.org/news/modernize-legacy-applications-with-ai/ 6a7e4a380ee61c58fa48acb3 Thu, 13 Aug 2026 22:50:32 +0000 I have seen legacy migrations considered successful because the old framework disappeared from the repository.

Six months later, the team was still dealing with the same coupling, the same unclear business rules, and almost the same deployment problems.

The technology had changed but the system hadn't changed very much as a whole.

AI makes this problem even more interesting.

It can translate code faster than a team could do manually. It can explain unfamiliar classes, generate tests, create adapters, update APIs, and remove a significant amount of repetitive work.

But if you point an AI coding tool at an old application and simply ask it to migrate everything to a modern stack, there's a good chance you'll get exactly what you asked for: the same system, rewritten faster.

That's not necessarily modernization.

In this tutorial, I want to show you a different way to use AI during a legacy migration.

Instead of treating AI as an automated code translator, you'll use it to help you:

  • understand an unfamiliar codebase,

  • identify business rules and hidden dependencies,

  • build a behavioral safety net,

  • find boundaries for incremental migration,

  • refactor before replacing,

  • automate repetitive transformations,

  • compare old and new behavior,

  • and detect regressions before they reach production.

The examples use TypeScript, but the process itself isn't tied to TypeScript or Node.js.

The important part is the workflow. AI can make migration work faster. But Engineering still has to decide what's worth migrating.

Prerequisites

You should be comfortable with:

  • basic TypeScript,

  • unit and integration testing,

  • dependency injection,

  • software architecture concepts,

  • and working with an existing codebase.

The examples use Vitest, but the same ideas apply if you use Jest or another testing framework.

Table of Contents

How to Avoid a One-to-One Legacy Migration

Imagine that you find this function in an old order-processing system:

async function processOrder(order: Order) {
  if (!order.customer.active) {
    throw new Error("Inactive customer");
  }

  const discount =
    order.customer.type === "PREMIUM"
      ? order.total * 0.1
      : 0;

  const finalAmount = order.total - discount;

  await db.orders.insert({
    customerId: order.customer.id,
    amount: finalAmount,
  });

  await paymentGateway.charge(
    order.customer.card,
    finalAmount,
  );

  await mailer.send(
    order.customer.email,
    "Order processed",
  );

  return finalAmount;
}

The function works, but it also does quite a lot.

It validates the customer, applies a pricing rule, persists data, charges a payment method, and sends a notification.

A one-to-one migration might turn this into a prettier TypeScript service with newer libraries while keeping all those responsibilities together.

You might replace an old controller with a new controller, an old service with a new service, and an old ORM with a new ORM...and still preserve the same architectural problem.

This is one of the first places where AI can work against you.

If your prompt is:

Convert this legacy class to TypeScript.

the model will normally preserve the structure because preserving the structure is the task you gave it.

Before asking AI to transform code, separate two questions:

  1. What behavior must survive?

  2. What design should survive?

Those aren't the same question.

Sometimes an implementation is old but its behavior is still essential. Sometimes the behavior matters but the implementation should disappear. And sometimes you discover that neither needs to survive.

That distinction should happen before the bulk migration begins.

How to Map a Legacy Codebase Before Changing It

The first difficult part of a legacy migration is usually understanding what you actually have.

Documentation helps when it exists. But in many systems, the real documentation is distributed across:

  • conditional statements,

  • database constraints,

  • scheduled jobs,

  • comments,

  • logs,

  • integration code,

  • tests,

  • configuration,

  • and knowledge that lives in people's heads.

This is an area where AI can save time without being asked to make architectural decisions.

Take the previous processOrder function. Instead of asking AI to rewrite it, start with questions such as:

Identify the business rules in this function.

List every side effect.

Which external systems does it depend on?

Which parts could be expressed as pure functions?

Which observable behaviors should probably be protected
with tests before this function is changed?

Do not rewrite the function.

The last instruction matters more than it may seem.

When analysis and transformation happen in the same request, it becomes easy for an AI tool to solve a design problem you haven't fully understood yet.

I prefer to make the analysis explicit first.

For a larger codebase, repeat the process at several levels.

At repository level, look for:

  • entry points,

  • database access,

  • external APIs,

  • message queues,

  • background jobs,

  • scheduled tasks,

  • configuration,

  • shared state,

  • authentication,

  • and authorization.

At module level, look for:

  • business rules,

  • dependencies,

  • side effects,

  • duplicated logic,

  • highly coupled classes,

  • and implicit contracts.

At function level, look for:

  • inputs,

  • outputs,

  • exceptions,

  • state changes,

  • external calls,

  • and edge cases.

AI can make this exploration much faster. But its findings should be checked against the actual repository, tests, schema, logs, and production behavior.

A confident explanation of the code is still only an explanation. The repository remains the source of truth.

How to Build Characterization Tests Before Refactoring

One of the uncomfortable parts of legacy software is that strange behavior is not necessarily accidental.

You may find code that looks obviously wrong and discover later that another part of the business depends on it.

This is where characterization tests are useful.

Michael Feathers discusses this approach in Working Effectively with Legacy Code: instead of beginning by describing how the system should behave, you first capture how it behaves today.

Consider this function:

export function calculateDiscount(
  customerType: string,
  total: number,
): number {
  if (customerType === "PREMIUM") {
    return total * 0.1;
  }

  return 0;
}

You can protect its current behavior with tests:

import { describe, expect, it } from "vitest";
import { calculateDiscount } from "./calculateDiscount";

describe("calculateDiscount", () => {
  it("applies a 10 percent discount to premium customers", () => {
    expect(
      calculateDiscount("PREMIUM", 100),
    ).toBe(10);
  });

  it("does not discount regular customers", () => {
    expect(
      calculateDiscount("REGULAR", 100),
    ).toBe(0);
  });

  it("returns zero when the order total is zero", () => {
    expect(
      calculateDiscount("PREMIUM", 0),
    ).toBe(0);
  });
});

AI is useful for expanding this safety net.

For example:

Generate characterization tests for this function.

Preserve the existing behavior.

Include:
- normal inputs,
- boundary values,
- invalid inputs,
- exceptions,
- observable side effects.

Do not redesign the function.

Then review what it generates.

You aren't proving that the old behavior is correct. You're recording what will change if you refactor it.

That difference matters.

If a test captures a behavior you later decide is a bug, change it intentionally. What you want to avoid is changing behavior accidentally and discovering the difference after deployment.

How to Find Safe Migration Seams

Legacy applications rarely need to be replaced all at once.

They usually need places where the old and new systems can coexist temporarily.

Feathers also describes the idea of a seam in Working Effectively with Legacy Code: a place where you can alter behavior without having to modify everything around it.

The order-processing example gives you one possible seam.

The original function contains:

  • customer validation,

  • discount calculation,

  • database persistence,

  • payment processing,

  • and email notification.

The first two belong naturally to business behavior. The others involve infrastructure. That suggests a possible boundary.

Domain/application responsibilities:

  • customer rules,

  • pricing rules,

  • order workflow.

Infrastructure responsibilities:

  • database,

  • payment provider,

  • email provider.

AI can help identify candidates for these boundaries.

For example:

Analyze these files and identify:

- business rules,
- infrastructure concerns,
- side effects,
- shared mutable state,
- duplicated logic,
- dependencies that make isolated testing difficult.

Suggest possible boundaries.

Do not rewrite the code yet.

Again, the AI output is input to an engineering decision. It shouldn't become the decision automatically.

When you find a good seam, you gain a place where modernization can progress without requiring a rewrite of the entire application.

How to Refactor Toward Explicit Responsibilities

Once you understand a section of the code and have tests around its current behavior, refactoring becomes less dangerous.

The pricing rule can become a pure function:

export function calculateDiscount(
  customerType: string,
  total: number,
): number {
  if (customerType === "PREMIUM") {
    return total * 0.1;
  }

  return 0;
}

Customer validation can be separated:

export function validateCustomer(
  customer: Customer,
): void {
  if (!customer.active) {
    throw new Error("Inactive customer");
  }
}

Infrastructure can move behind contracts:

export interface OrderRepository {
  save(order: PersistedOrder): Promise<void>;
}

export interface PaymentGateway {
  charge(
    card: string,
    amount: number,
  ): Promise<void>;
}

export interface NotificationService {
  sendOrderConfirmation(
    email: string,
  ): Promise<void>;
}

The application workflow becomes easier to read:

export class ProcessOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
    private readonly notifications: NotificationService,
  ) {}

  async execute(order: Order): Promise<number> {
    validateCustomer(order.customer);

    const discount = calculateDiscount(
      order.customer.type,
      order.total,
    );

    const finalAmount =
      order.total - discount;

    await this.orders.save({
      customerId: order.customer.id,
      amount: finalAmount,
    });

    await this.payments.charge(
      order.customer.card,
      finalAmount,
    );

    await this.notifications.sendOrderConfirmation(
      order.customer.email,
    );

    return finalAmount;
  }
}

There's nothing particularly revolutionary in this refactoring. That's part of the point.

Modernization doesn't require an exotic architecture.

Often the important improvement is simply making responsibilities explicit enough that the next change doesn't require understanding the entire application.

How to Use AI for Mechanical Transformations

Once the boundaries are clear, AI becomes much more useful for implementation.

A surprising amount of migration work is necessary but repetitive:

  • translating APIs,

  • replacing framework conventions,

  • generating adapters,

  • converting configuration,

  • updating type definitions,

  • changing data access libraries,

  • and updating repetitive integration code.

These are good places to use AI.

Imagine that the old system performs SQL directly:

async function getCustomer(id: number) {
  const result = await db.query(
    `SELECT * FROM customer WHERE id = ${id}`,
  );

  return result[0];
}

Before generating the new implementation, define the contract you want:

export interface CustomerRepository {
  findById(id: number): Promise<Customer | null>;
}

Then constrain the transformation:

Implement CustomerRepository using the new database client.

Constraints:

- Keep the CustomerRepository interface unchanged.
- Use parameterized queries.
- Do not move business rules into the repository.
- Preserve the existing null behavior.
- Preserve the existing error semantics.
- Return only the implementation.

This is a very different request from:

Modernize this database code.

In the first case, you made the architectural decision and asked AI to implement within that boundary.

That is where I find AI most useful in migration work. It removes mechanical effort after the important decisions have already been made.

How to Migrate in Small Vertical Slices

Large migrations become difficult to reason about when thousands of files change together.

A safer unit of change is often a business capability.

Instead of migrating all controllers, then all services, and finally all repositories, migrate one complete capability.

For example:

Create Order

  • API

  • application logic

  • domain rules

  • persistence

  • tests

Then move to the next capability.

This has several advantages. First, the migration remains closer to deployable software. Second, the context you give an AI tool stays smaller.

Testing also becomes more focused. And if something goes wrong, the failure is easier to isolate.

A useful first prompt for a vertical slice is analysis-only:

We are migrating the Create Order capability.

The legacy implementation is under /legacy/orders.

The target architecture separates:
- domain,
- application,
- infrastructure.

The characterization tests under /tests/legacy
describe behavior that must remain compatible.

Analyze the current implementation.

List:
1. business rules,
2. external dependencies,
3. side effects,
4. likely migration risks,
5. files that need to change.

Do not generate code yet.

Review that output, then plan the actual transformation.

This is also compatible with an incremental replacement strategy such as Martin Fowler's Strangler Fig approach, where new functionality gradually takes over from an older system instead of requiring one large cutover.

The important word is gradually.

AI can increase transformation speed. That doesn't make a big-bang migration less risky.

How to Compare Legacy and Modern Behavior

Unit tests give you one kind of safety.

For a migration, I also like comparing the old and new implementations directly.

Suppose both systems can process the same order. You can run the same fixture through each one:

const inputs = [
  premiumCustomerOrder,
  standardCustomerOrder,
  inactiveCustomerOrder,
];

for (const input of inputs) {
  const legacyResult =
    await legacyProcessor(input);

  const modernResult =
    await modernProcessor(input);

  expect(modernResult).toEqual(legacyResult);
}

This is a simple form of differential testing. You can do the same thing at the HTTP boundary.

Send the same POST /orders request to both versions and compare:

  • status codes

  • response payloads

  • database changes

  • emitted events

  • external calls

  • errors

An important point: a difference isn't automatically a bug. Sometimes behavior is supposed to change. The useful thing is making the difference visible so someone has to classify it deliberately.

AI can help here too.

If you have hundreds of mismatches, you can ask it to group them:

Analyze these behavioral mismatches.

Group them by likely cause.

Pay particular attention to:
- rounding,
- null handling,
- timezone conversion,
- validation,
- serialization,
- data mapping.

Do not label a mismatch as a defect unless the
available evidence supports that conclusion.

This is a good use of AI because the model is reducing investigation work. It's not deciding whether production behavior is acceptable.

How to Use Shadow Traffic to Find Regressions

Eventually, test fixtures stop being representative enough.

Production systems receive combinations of inputs nobody thought to put into a test suite.

One way to observe those differences is shadow traffic. The legacy application continues serving the user's request, and a copy of that request also goes to the new implementation. The new result is used for comparison only and isn't returned to the user.

For example:

Legacy:
200
{ "total": 90 }

Modern:
200
{ "total": 90 }

MATCH

Or:

Legacy:
200
{ "total": 90 }

Modern:
200
{ "total": 100 }

MISMATCH

Collecting those mismatches gives you evidence about how the new system behaves under real traffic without immediately exposing users to it.

This technique comes with operational considerations. You need to think carefully about:

  • duplicated side effects,

  • payment calls,

  • emails,

  • writes,

  • privacy,

  • production load,

  • and external API usage.

A shadow instance should generally avoid performing irreversible side effects.

For example, replace the real payment adapter with a recording adapter:

export class RecordingPaymentGateway
  implements PaymentGateway {

  public readonly calls: Array<{
    card: string;
    amount: number;
  }> = [];

  async charge(
    card: string,
    amount: number,
  ): Promise<void> {
    this.calls.push({
      card,
      amount,
    });
  }
}

Now you can compare the intention to charge without charging a customer twice.

How to Test the Architecture You Actually Want

Behavioral compatibility isn't enough if one objective of the migration is improving the architecture.

Imagine that you've decided on this constraint:

Domain code must not depend on infrastructure code.

If that rule only exists in an architecture diagram, migration pressure will eventually break it.

So test it.

For a simple project, you can inspect imports. For a larger one, use a dependency-analysis tool capable of enforcing architectural rules.

The exact tooling matters less than the principle:

If an architectural constraint matters, make breaking it visible.

You may want rules such as:

  • domain must not depend on infrastructure

  • domain must not depend on the HTTP framework

  • application code must not depend directly on the database driver

  • modules must not import another module's internal implementation

Why does this matter in an AI-assisted migration? Because AI is very good at finding a way to make code compile.

If reaching directly into another module solves the immediate problem, generated code may do exactly that unless the boundary is part of the constraints.

Architecture tests give both humans and AI tooling a harder boundary to violate accidentally.

How to Decide Which Tasks AI Should Handle

I don't treat all migration tasks equally. Some are good candidates for automation.

Tasks Where AI Is Usually Useful

  • explaining unfamiliar code

  • identifying dependencies

  • extracting candidate business rules

  • generating characterization test cases

  • generating repetitive adapters

  • updating framework APIs

  • translating mechanical code

  • creating migration checklists

  • comparing implementations

  • classifying regression output

  • drafting technical documentation

Tasks Where I Want Significant Engineering Review

  • proposing module boundaries

  • extracting domain concepts

  • refactoring highly coupled classes

  • choosing migration sequences

  • changing data models

  • designing integration boundaries

Decisions I Would Keep Under Human Ownership

  • target architecture

  • acceptable behavioral differences

  • security boundaries

  • data migration strategy

  • rollout strategy

  • rollback strategy

  • removal of legacy behavior

  • production risk acceptance

This isn't because AI can't produce an architecture proposal. It can.

The problem is accountability and context.

Architecture choices are consequences of constraints, history, organizational capabilities, business priorities, and operational risks that may not exist anywhere in the repository.

A model can help you explore those choices, but someone still has to own them.

How to Measure Whether the Migration Actually Improved the System

Migration velocity is an attractive metric because it's easy to show.

For example:

37% of the codebase migrated.

That doesn't tell you much about whether the system became better.

A modernization effort should look at several kinds of outcomes. Operational metrics might include:

  • deployment frequency

  • change failure rate

  • mean time to recovery

  • production incidents

  • build time

Engineering metrics might include:

  • test coverage

  • high-complexity classes

  • duplicated business rules

  • cross-module dependencies

  • architectural violations

  • time required to change a capability

Migration-specific metrics might include:

  • regression rate

  • percentage of traffic handled by the new path

  • unresolved behavioral mismatches

  • rollback frequency

  • legacy components still in use

The exact metrics depend on the system. What matters is avoiding this definition of success:

Old repository is smaller = modernization succeeded.

AI makes it possible to transform more code in less time. That makes measuring the quality of the transformation more important, not less.

The Risk I Worry About Most with AI-Assisted Migration

Hallucinated code is a clear risk. But I worry more about plausible code.

Generated code can compile. It can look cleaner than the original implementation. It can even pass a shallow test suite. And it can still subtly change a business rule that nobody realized existed.

Consider something as small as:

if (customer.balance > 0) {
  charge(customer);
}

It's tempting to clean up code when you don't understand why a condition exists.

But maybe zero has a special business meaning.

Maybe negative balances are legitimate.

Maybe the condition was introduced after a production incident six years ago and never documented.

AI can't recover context that doesn't exist in the information available to it. This is why I put so much emphasis on characterization tests and behavioral comparison.

The faster the transformation becomes, the stronger the validation process needs to become.

Otherwise, you're only increasing the speed at which you can introduce unknown changes.

A Practical Migration Workflow

If I had to reduce the process to one repeatable sequence, I would use this.

1. Understand

Map:

  • behavior

  • dependencies

  • business rules

  • side effects

  • data

  • integrations

Use AI to accelerate the investigation. Don't start by generating the new system.

2. Protect

Build:

  • characterization tests

  • integration tests

  • API fixtures

  • behavioral snapshots

Make current behavior observable.

3. Design

Choose:

  • boundaries

  • interfaces

  • responsibilities

  • migration seams

Do this before large-scale transformation.

4. Refactor

Create enough separation that part of the system can move without dragging everything else with it.

5. Transform

Use AI heavily for repetitive implementation work.

Give it explicit architectural constraints.

6. Compare

Run old and new behavior against the same inputs and investigate differences.

7. Release Gradually

Use the mechanisms appropriate for your environment:

  • feature flags

  • canary deployments

  • shadow traffic

  • observability

  • rollback

8. Remove the Old Path

Don't leave both systems running indefinitely. A migration that never removes the legacy path eventually creates another legacy architecture.

Conclusion

AI changes the economics of legacy modernization.

A lot of work that used to consume engineering hours can now happen much faster: reading unfamiliar code, generating tests, updating APIs, translating repetitive implementations, and investigating differences between systems.

That's useful. But it's not the part of modernization that requires the most judgment.

The difficult questions remain:

  • What behavior still matters?

  • What should disappear?

  • Which dependencies should survive?

  • Where should the boundaries be?

  • How much behavioral change is acceptable?

  • When is the new implementation safe enough to receive production traffic?

If you use AI only to translate code, you can migrate technical debt faster.

If you combine it with characterization testing, incremental refactoring, explicit architectural boundaries, differential testing, and controlled rollout, you have a better chance of improving the system while you move it.

The objective isn't to move the same system onto a newer stack. It's to understand it, protect its important behavior, refactor it, migrate it incrementally, validate the result, and end up with a simpler system than the one you started with.

AI can shorten that path. But it still can't decide what the destination should be.

]]> <![CDATA[ Stop Trusting AI Code Blindly: A React Code Refactoring Case Study ]]> https://www.freecodecamp.org/news/stop-trusting-ai-code-blindly-a-react-code-refactoring-case-study/ 6a2054b908e3e46121ab26ae Wed, 03 Jun 2026 16:22:17 +0000 If you're a developer (or even a little bit familiar with all the AI developments of the past few years), the term Vibe Coding shouldn't be new to you. It is a software development practice where you describe what you want to AI (an LLM) in plain English, and in response, it gives you the source code for it.

You don't write anything manually line-by-line. You just completely focus on the vibe, like features, look-and-feel, and so on – and the AI generates the actual code for you. It's amazing and powerful.

Like millions of other software developers, I use and advocate the use of AI to a great extent. We should be using AI as a tool to expedite deliverables, to get repetitive work done, to make boilerplate, and anything that AI can help us with to stay productive.

But we shouldn't be doing any of this blindly, especially when it comes to delivering AI-generated work to customers.

All the modern AI tools like Claude, Gemini, or ChatGPT provide a warning upfront that AI can make mistakes. And we as users must double-check the responses before using them. Here's a similar notice from Claude:

Claude AI notice

The main message is this: don't trust AI-generated code blindly. You must do your due diligence before you think of pushing it to production.

To illustrate this, in this article you'll learn from a recent case study I did on generating some React-based source code for an Analytics Dashboard app with AI.

The AI gave me some error-free source code that I could run to see the app. But when I started digging deeper into it, I found potential bugs and tech debt that I needed to address. The generated source code was far from being ready for production and needed a great deal of refactoring.

This guide is also available as a video tutorial as part of the Full-Stack: Vibe Coding to Production Ready series. You can check it out if you’d like:

Let's start.

Table of Contents

  1. The Prompt

  2. The Generated React Code

  3. The Dashboard App

  4. The Code Walkthrough and Identifying Problems

  5. Refactoring the AI-Generated Code

  6. A Task for You

  7. Key Takeaways

  8. If You've Read This Far...

The Prompt

First, we need a prompt to inform the AI in plain English that it should generate the source code for the Analytics Dashboard.

Here is the prompt – read it carefully:

Act as an expert React developer. 

I need a complex 'Creator Analytics Dashboard' for a video platform created using React.

It should include: 

- 1. A header with a user profile. 
- 2. Three summary cards showing total views, videos, and comments. 
- 3. A data table showing recent videos with their individual stats. 
- 4. A sidebar with navigation options. 

Use Tailwind CSS for styling. 

Fetch fake data for the dashboard using fetch with a 1-second timeout to simulate a network request. 

Make it in a way so that I can copy and paste it easily.

It's a straightforward request to create a Creator Analytics Dashboard with a bunch of feature requests using React and TailwindCSS.

Now, if we take up this prompt and use it on any of the AI tools like ChatGPT, Claude, or Gemini, it will generate the source code for us automatically.

The Generated React Code

Here's the AI-generated source code from the prompt. As you can see, it's a complete React component with state management, side effect management, and JSX.


import { useEffect, useState } from "react";

export default function CreatorDashboard() {
  const [stats, setStats] = useState({ views: 0, subs: 0, revenue: 0 });
  const [videos, setVideos] = useState([]);
  const [comments, setComments] = useState([]);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    let isMounted = true;

    const fetchData = async () => {
      try {
        await new Promise((resolve) => setTimeout(resolve, 1000));

        if (isMounted) {
          setStats({ views: '1.2M', subs: '45K', revenue: '$3,400' });
          setVideos([
            { id: 1, title: 'Vibe Coding Explained', views: '100K' },
            { id: 2, title: 'React 19 Features', views: '85K' }
          ]);
          setComments([{ id: 1, text: 'Great video!' }]);
          setIsLoading(false);
        }
      } catch (err) {
        setError('Failed to fetch data');
        setIsLoading(false);
      }
    };

    fetchData();
    return () => { isMounted = false; };
  }, []);

  if (isLoading) return <div className="p-10 text-center text-xl">Loading Dashboard...</div>;
  if (error) return <div className="text-red-500 p-10">{error}</div>;

  return (
    <div className="flex bg-gray-100 min-h-screen">
      
      <div className="w-64 bg-white shadow-md p-4">
        <h2 className="text-2xl font-bold mb-6 text-blue-600">tapaScript</h2>
        <ul>
           <li className="mb-2 p-2 bg-blue-50 text-blue-700 rounded cursor-pointer">Dashboard</li>
           <li className="mb-2 p-2 hover:bg-gray-50 rounded cursor-pointer">Analytics</li>
        </ul>
      </div>

      <div className="flex-1 p-8">
        
        <header className="flex justify-between items-center mb-8">
          <h1 className="text-3xl font-bold text-gray-800">Creator Analytics</h1>
          <div className="flex items-center gap-2">
            <div className="w-10 h-10 bg-blue-500 rounded-full"></div>
            <span className="font-semibold">Tapas Adhikary</span>
          </div>
        </header>

        
        <div className="grid grid-cols-3 gap-6 mb-8">
          <div className="bg-white p-6 rounded-lg shadow-sm border border-gray-100">
            <h3 className="text-gray-500 text-sm font-medium">Total Views</h3>
            <p className="text-3xl font-bold mt-2">{stats.views}</p>
          </div>
        </div>

        <div className="grid grid-cols-3 gap-8">
           <div className="col-span-2 bg-white rounded-lg shadow-sm p-6">
              <h2 className="text-xl font-bold mb-4">Recent Videos</h2>
              {videos.map(v => <div key={v.id} className="border-b p-3">{v.title}</div>)}
           </div>
           <div className="bg-white rounded-lg shadow-sm p-6">
              <h2 className="text-xl font-bold mb-4">Recent Comments</h2>
              {comments.map(c => <div key={c.id} className="border-b p-3 text-sm text-gray-600">{c.text}</div>)}
           </div>
        </div>
      </div>
    </div>
  );
}

Note that if you try the same prompt again, it will generate slightly different source code as the LLM's responses are probabilistic and non-deterministic. It can produce different responses for the same prompt across multiple calls.

Alright, let's try out the generated code.

The Dashboard App

Now, copy that AI-generated code and paste it into any React project. When you run it, you should see a beautiful Creator Analytics Dashboard matching the functionalities mentioned in the prompt.

Dashboard UI

This is amazing and powerful. As a developer, we must leverage it as much as possible. But as a developer, you also need to act like human guardrails to make sure that the generated code is modular, scalable, and bug-free.

Let's now do the walkthrough of the AI-generated code.

The Code Walkthrough and Identifying Problems

Before you read further, go back and read the generated source code once more. This time, slowly, carefully – like a code reviewer.

What have you found? Let's see if your findings match the list from my case study.

Problem 1: The God Component Syndrome

In software engineering, we have the Single Responsibility Principle(SRP). It means a function or component should do exactly one thing.

But here, our CreatorDashboard is acting as a "God Component". It manages state, it fetches data from the network, it renders the sidebar, it renders the header, the card, the tables...everything.

If the marketing team asks you to reuse that Stats Card on the marketing landing page, you simply can't. You need to rewrite it, as it's locked inside the giant file.

Problem 2: The State Soup Problem

Look at the top of the component. Five different useState declarations. When a component renders, tracking which piece of text triggered it becomes a nightmare. This should either be grouped or, even better, managed by a dedicated data fetching library like TanStack Query.

Remember, the fewer states you manage in your component, the better your life will be as a React developer.

Problem 3: The Data Fetching Anti-Pattern

AI loves to use useEffect for data fetching. It's one of the biggest anti-patterns in modern React. This is because the hook useEffect was never meant for data fetching. It doesn't handle caching, it doesn't handle retries if the network drops, and if the user navigates away and comes back, it forces a hard reload on the data every single time.

Modern React provides a better mechanism for data fetching. I've written a Handbook on how to use Suspense and Error Boundary to handle data fetching in React. You can give it a read.

Problem 4: The Missing Types Problem

We haven't mentioned TypeScript explicitly in the prompt. So, AI gave us JavaScript by default. Now, the problem is, can we guarantee what the videos array holds? What does a video object look like? We don't know, and our editor also can't help us.

Refactoring the AI-Generated Code

Now that we've identified the problems, the next logical step is to refactor the code to make it better.

Refactoring Strategy

The image below shows the refactoring strategy we'll follow. We'll break the giant AI-generated component into logical, smaller components like Header, Sidebar, RecentComments, and so on.

We also need to handle the data outside of the component and make the data fetching mechanism reusable for other components in the application to leverage it. To do this, we'll apply the Custom Hook Pattern.

Refactored code strategy

Define Types

First, let's define all the types needed for the data objects. We need type definitions for video status, comments, and overall creator status.


// We use 'type' or 'interface' in TypeScript to define the shape of an object.

export interface CreatorStat {
  label: string;
  value: string | number;
}

export interface VideoStats {
  id: string; // ID should always be a string (UUID) or number, we'll enforce string here
  title: string;
  views: number;
  publishedAt: string;
}

export interface Comment {
  id: string;
  author: string;
  text: string;
  createdAt: string;
}

Break the Monoliths

Next, we'll solve the problem of SRP violation and the problem of CreatorDashboard being a God Component. Refactor the giant component by breaking it into multiple smaller components:

  • Header: A component represents the header of the analytics dashboard.
function Header() {
    return (
        <header className="flex justify-between items-center mb-8">
            <h1 className="text-3xl font-bold text-gray-800">
                Creator Analytics
            </h1>
            <div className="flex items-center gap-2">
                <div className="w-10 h-10 bg-blue-500 rounded-full"></div>
                <span className="font-semibold">Tapas Adhikary</span>
            </div>
        </header>
    );
}

export default Header;
  • Sidebar: The sidebar component holds the navigation links.
export default function Sidebar() {
    return (
        <div className="w-64 bg-white shadow-md p-4">
            <h2 className="text-2xl font-bold mb-6 text-blue-600">
                tapaScript
            </h2>
            <ul>
                <li className="mb-2 p-2 bg-blue-50 text-blue-700 rounded cursor-pointer">
                    Dashboard
                </li>
                <li className="mb-2 p-2 hover:bg-gray-50 rounded cursor-pointer">
                    Analytics
                </li>
            </ul>
        </div>
    );
}
  • StatCard: This component accepts a status label and value and renders them. Note how we've applied the types here on the label and value props.
// 1. We define the Props interface.
// "Props" are the arguments passed into a React component.
// We are enforcing that whoever uses this component MUST pass a label and a value.
interface StatCardProps {
    label: string;
    value: string | number;
}

// 2. We extract the props cleanly using destructuring: { label, value }
function StatCard({ label, value }: StatCardProps) {
    return (
        <div className="bg-white p-6 rounded-lg shadow-sm border border-gray-100 hover:shadow-md transition-shadow">
            <h3 className="text-gray-500 text-sm font-medium uppercase tracking-wider">
                {label}
            </h3>
            <p className="text-3xl font-extrabold mt-2 text-gray-900">
                {value}
            </p>
        </div>
    );
}

export default StatCard;
  • VideoTable: This component lists out all the video information. So, it accepts an array of videos. Notice that we've solved the type problem here. Now we know that each video in the videos array is of the VideoStats type that we defined earlier.

import type { VideoStats } from '../types';

interface VideoTableProps {
  // We expect an array of VideoStats objects.
  videos: VideoStats[];
}

function VideoTable({ videos }: VideoTableProps) {
  if (videos.length === 0) {
    return <div className="p-6 text-center text-gray-500">No videos uploaded yet.</div>;
  }

  return (
    <div className="bg-white rounded-lg shadow-sm border border-gray-100 overflow-hidden">
      <div className="p-4 border-b border-gray-100 bg-gray-50">
        <h2 className="text-lg font-bold text-gray-800">Recent Videos</h2>
      </div>
      <ul className="divide-y divide-gray-100">
        {videos.map((video) => (
          <li key={video.id} className="p-4 hover:bg-gray-50 flex justify-between items-center">
            <span className="font-medium text-gray-900">{video.title}</span>
            <span className="text-sm bg-blue-100 text-blue-800 py-1 px-3 rounded-full font-semibold">
              {video.views.toLocaleString()} views
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default VideoTable;
  • RecentComments: A component to show the list of comments.
import type { Comment } from "../types";

interface RecentCommentProps {
    // We expect an array of Comment objects.
    videos: Comment[];
}

function RecentCommentList({ comments }: RecentCommentProps) {
    if (comments.length === 0) {
        return (
            <div className="p-6 text-center text-gray-500">
                You don't have any comments posted.
            </div>
        );
    }

    return (
        <div className="bg-white rounded-lg shadow-sm p-6">
            <h2 className="text-xl font-bold mb-4">Recent Comments</h2>
            {comments.map((c) => (
                <div key={c.id} className="border-b p-3 text-sm text-gray-600">
                    {c.text}
                </div>
            ))}
        </div>
    );
}

export default RecentCommentList;

Custom Hook to Handle Data

Now that we have the components defined, and all of them are presentational components, they need data to render information on the dashboard. Also, we don't want to handle all the states inside our component. A custom hook would be a great choice here.

The hook handles the fetch call to get analytics data and tracks them using the state. We return the needed state values from the hook so that anyone using the hook anywhere would get this information. It's completely reusable.

import { useEffect, useState } from "react";
import type { Comment, CreatorStat, VideoStats } from "./types";

export function useDashboardData() {
    const [stats, setStats] = useState<CreatorStat[]>([]);
    const [videos, setVideos] = useState<VideoStats[]>([]);
    const [comments, setComments] = useState<Comment[]>([]);
    const [isLoading, setIsLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);

    useEffect(() => {
        let isMounted = true;

        const fetchData = async () => {
            try {
                // Simulating an API call
                await new Promise((resolve) => setTimeout(resolve, 1000));

                if (isMounted) {
                    setStats([
                        { label: "Views", value: "1.2M" },
                        { label: "subs", value: "45K" },
                        { label: "revenue", value: "$3,400" },
                    ]);
                    setVideos([
                        {
                            id: 1,
                            title: "Vibe Coding Explained",
                            views: "100K",
                        },
                        { id: 2, title: "React 19 Features", views: "85K" },
                    ]);
                    setComments([
                        { id: 1, text: "Great video!" },
                        { id: 2, text: "Fantastic video!" },
                    ]);
                    setIsLoading(false);
                }
            } catch (err) {
                setError(`Failed to fetch data: ${err?.message}`);
                setIsLoading(false);
            }
        };

        fetchData();
        return () => {
            isMounted = false;
        };
    }, []);

    return {
        stats,
        videos,
        comments,
        isLoading,
        error
    }

}

Everything Together

Finally, it's time to change the giant CreatorDashboard component. We'll first import all the smaller components created, and then call the hook to get the stats, videos, comments, and loading and error states. After that, it's just about using them.

import Header from "@/components/Header";
import Sidebar from "@/components/Sidebar";
import RecentCommentList from "./components/RecentComments";
import StatCard from "./components/StatCard";
import VideoTable from "./components/VideoTable";

import { useDashboardData } from "./hooks/useDashboardData";

export default function CreatorDashboard() {
    const { stats, videos, comments, isLoading, error } = useDashboardData();

    if (isLoading)
        return (
            <div className="p-10 text-center text-xl">Loading Dashboard...</div>
        );
    if (error) return <div className="text-red-500 p-10">{error}</div>;

    return (
        <div className="flex bg-gray-100 min-h-screen">
            {/* Sidebar Navigation */}
            <Sidebar />

            <div className="flex-1 p-8">
                {/* Header */}
                <Header />

                {/* Stats Cards */}
                <div className="grid grid-cols-3 gap-6 mb-8">
                    {stats.map((stat) => (
                        <StatCard
                            key={stat.label}
                            label={stat.label}
                            value={stat.value}
                        />
                    ))}
                </div>

                {/* Data Table & Comments - All mashed together */}
                <div className="grid grid-cols-3 gap-8">
                    <div className="lg:col-span-2">
                        <VideoTable videos={videos} />
                    </div>
                    <RecentCommentList comments={comments} />
                </div>
            </div>
        </div>
    );
}

That's all. We have now successfully refactored the big AI-generated component into smaller, reusable components and separated the data layer and state handling outside of it.

A Task for You

This is optional, yet I'd encourage you to try it. The task is to take the refactoring to the next level.

Can you get rid of the useDashboardData hook, and handle the data fetching using the Suspense and Error Boundary patterns? I would love to discuss the solution with you. Please reach out on my socials (given below) or my Discord Server.

Also, stay tuned for my upcoming article, where I'll refactor the same app with TanStack Query and teach you about fetch, mutation, and caching.

Key Takeaways

This is the reality of AI-generated code. It looks like a finished product on the surface. But underneath, it's a fragile house of cards. If you try to scale this, say by adding authentication, sorting to the tables, or real-time comment updates, the file will grow to 1K+ lines of unmaintainable code.

Our job isn't to reject AI's output. Instead, it's to refactor its output to make it production-ready. You can do that only when you have strong fundamentals, and you understand the new definition of software engineering in the age of AI.

If You've Read This Far...

Thank You!

I'm thrilled to announce that I've started a Full Stack FREE Course to take developers from vibe coding to a production-ready mental model. I'd be delighted if you check it out and take part.

See you soon with my next article. Until then, please take care of yourself and keep learning.

]]> <![CDATA[ How to Refactor Complex Codebases – A Practical Guide for Devs ]]> https://www.freecodecamp.org/news/how-to-refactor-complex-codebases/ 682df5a0f2057ab279952dbe Wed, 21 May 2025 15:47:44 +0000 Developers often see refactoring as a secondary concern that they can delay indefinitely because it doesn’t immediately contribute to revenue or feature development.

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.

code-refactoring

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.

Uncle-bob-take-on-refactoring

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?

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.

martin-fowler-on-refactoring

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.

automated-testing-is-imp-for-refactoring

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.

SonarQube-dashboard

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.

SonarQube

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).

code-health-dashboard

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).

Branch-by-abstraction

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 refactoring

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.

microservices' advantages

  • 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​.

Clear deprecation policy

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)

Introduce interfaces or abstraction layers

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.

Facades or wrapper services

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​.

Canary releases and feature flags

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

profiler-dashboard

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.

CodeRabbit-ai-code-reviewer-tool

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.

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.

]]> <![CDATA[ How to Refactor to Configurable Dependency in 5 Steps ]]> https://www.freecodecamp.org/news/refactoring-to-configurable-dependency-in-5-steps/ 66d45dea4a7504b7409c335b Fri, 19 Aug 2022 20:42:23 +0000 By Bertil Muth

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.

Image

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.

Image

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.

]]> <![CDATA[ Code Refactoring Best Practices – with Python Examples ]]> https://www.freecodecamp.org/news/best-practices-for-refactoring-code/ 66bae7cf02a6638884966f13 Thu, 18 Aug 2022 15:15:29 +0000 In this article, I will discuss what code refactoring is. We'll go over why you need to refactor your code, the advantages of code refactoring, and some best practices for code refactoring.

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:

#Using the Force formula F=ma

while True:
  mass = int(input("Enter the mass value: "))
  if mass > 0:
    break
while True:
  acceleration = int(input("Enter the acceleration: "))
  if acceleration > 0:
    break
print("The Force is", mass * acceleration)

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:

#REFACTORED code

def input_positive_integer(prompt):
  while True:
    input_value = int(input(prompt))
    if input_value > 0:
      return input_value
mass = input_positive_integer("Enter the mass: ")
acceleration = input_positive_integer("Enter the acceleration: ")
print("The Force is", mass * acceleration)

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:

#List Comprehension instead of For Loop

numbers = [1,2,3,4,5,6,7,8]
odd_numbers = []
for item in numbers:
  if item % 2 == 1:
    odd_numbers.append(item)
print(odd_numbers)

#Outcome will be [1,3,5,7]

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:

numbers = [1,2,3,4,5,6,7,8]
odd_numbers = [item for item in numbers if item % 2 == 1]
print (odd_numbers)

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:

#Using the Work done expression W=fd

while True:
  force = int(input("Enter the force value:  "))
  if force > 0:
    break
while True:
  distance = int(input("Enter the distance value:  "))
  if distance > 0:
    break
print("The Workdone is", force distance)

Refactored code:

#REFACTORED code

def input_positive_integer(prompt):
  while True:
    input_value = int(input(prompt))
    if input_value > 0:
      return input_value
force = input_positive_integer("Enter the force value:  ")
distance = input_positive_integer("Enter the distance:  ")
print("The Workdone is", force * distance, "J")

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:

# USING TERNARY OPERATOR

to_check = int(input("Enter a whole number :"))
msg = "Even" if to_check%2 == 0 else "Odd"
print("The number you entered is", msg, "number")


# USING USUAL IF-ELSE

to_check = int(input("Enter a whole number :"))
msg = ""
if(to_check%2 == 0):
  msg = "Even"
else:
  msg = "Odd"
print("The number you entered is", msg, "number")


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:

colors = ["white", "black", "brown"]
for i in range(len(colors)):
  print(i+1, colors[i])
# 1 white
# 2 black
# 3 brown

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:

colors = ["white", "black", "brown"]
for i, colors in enumerate(colors, 1):
  print(i, colors)
 
# 1 white
# 2 black
# 3 brown

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.

]]> <![CDATA[ How to Make Calculation Tests Simpler and More Expressive with These New Refactorings ]]> https://www.freecodecamp.org/news/how-to-test-complicated-calculations-new-refactoring/ 66bb9264fce17a7d99885305 Wed, 03 Feb 2021 17:32:34 +0000 It is a good idea to make tests as descriptive as possible – to achieve Tests as Documentation. Including the calculations in the test is a big part of this, and avoids the Hard Coded Test Data smell.

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!

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.

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.

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.

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.

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.

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.

]]> <![CDATA[ Why You Should Refactor Your Code ]]> 's and 's. Use functional React components. Try to avoid arrow function in render. And do not repeat yourself! Before I go straigh... ]]> https://www.freecodecamp.org/news/why-you-should-refactor-your-code/ 66be14d94acec4a9c337d05e Fri, 03 Apr 2020 20:00:25 +0000 Raise your hand if any of the following sounds familiar: Think about code formatting. Get rid of unnecessary <div>'s and <span>'s. Use functional React components. Try to avoid arrow function in render. And do not repeat yourself!

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!

]]> <![CDATA[ How Code Becomes A Dumping Ground (And How To Fix It!) ]]> https://www.freecodecamp.org/news/fixing-code-dumping-grounds/ 66d45f31a3a4f04fb2dd2e57 Wed, 18 Sep 2019 20:36:52 +0000 By James Hickey

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.

]]> <![CDATA[ When to refactor legacy code vs. when to stay focused on your current project ]]> https://www.freecodecamp.org/news/when-to-refactor-legacy-code-vs-when-to-stay-focused-on-your-current-project-fda99919cc34/ 66c3665109a9333511bcdb63 Fri, 08 Feb 2019 21:14:01 +0000 By Sihui Huang

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.

]]>