Legacy code is any code you inherit

What Makes Code “Legacy”?

Legacy code isn’t necessarily bad or even that old. It’s code that:

1. You didn’t write - It lacks your mental model and intentions
2. Powers important systems - It can’t simply be replaced
3. Contains institutional knowledge - Sometime undocumented! Decisions were often made for good reasons which we may not remember any more, and changing those decisions may be risky.

The Purple Forest application is now your legacy code. Someone else designed and built it, and you need to maintain and extend it.

Working with Purple Forest

Purple Forest has:

• Established architecture - It follows defined patterns
• Functional system - It mostly works, even if you don’t understand how
• Multiple components - Changes might have unexpected side effects
• Documented design - But the documentation might be incomplete or out of date

So how do you approach understanding and working with this legacy codebase?

Do you remember your first day at CYF? You couldn’t find the building, maybe, and you had no idea how the day would go. What on earth is a day plan, or a backlog, you thought to yourself. Perhaps you got frustrated: why are all my changes from last week in my new PR? How?! It was incomprehensible. But you learned! You asked questions, you read the guides, and you built a mental map of the system.

You might have found your first code reviews challenging too. You worked on a project for days, just got it all working, and now someone is telling you to change it. Changing code you don’t understand very well feels risky.

Feeling a bit hesitant is fine. In fact, some caution is healthy. If code is working and it’s doing something important for the business, we don’t want to break it. But we also don’t want to be so fearful that we can’t fix it or write new features. We must balance caution with curiosity. We will approach legacy code with a structured, logical plan.

A good rule here is Chesterton’s Fence. This says that before we change something, we must explain why it’s like that in the first place.

In code, Chesterton’s Fence comes up a lot when we read code that looks complicated. It’s easy to think “This code could be simpler”. And maybe it could! There are a lot of reasons code is more complicated than it could be. Maybe it is complicated because:

• ✅ the person who wrote it didn’t know a better way. If so, we can simplify it.
• ✅ the simpler way was only introduced to the language after the code was written. If so, we can simplify it.
• 🚫 we want to support old versions of the language when the simpler way didn’t exist. If so, we can’t simplify it: we would break something important!
• 🚫 some important edge-case we hadn’t considered. If so, we need to understand that edge-case before we can change it, or we’ll break it.

Understanding why is crucial here. Tests can help us to understand. If we simplify the code and a test for a particular edge-case breaks, we found out why the code was more complicated! Comments can help too. A comment saying “We don’t do the simpler thing because it doesn’t handle undefined properly” tells us why the code is more complicated. But sometimes legacy code doesn’t have useful tests or comments.

By tracing request flows, drawing maps, and using code search tools, you can efficiently find your way through legacy code.

1. 🔍 Find

We’re going to use the features of our IDE to help us. VSCode has a million features for this, but we’re just going to start with four: Open file, Find references, Peek definition, and Find in files.

2. 📞 Trace a Request Flow

Open Purple Forest on your local machine. Read the README to get it running, and launch the frontend with Live Server. Again, Devtools has a million features but we’re going to use four: Event Listener panel, Network panel, Sources panel, and Local Storage in the Application panel.

Note: Your completed flowchart should show a sequence from the user click to the UI update. Label the answers to the following questions:

• What function makes a request to the server?
• What is the endpoint?
• What comes back from the server?
• Where does that response go next?
• What drives the UI update?

3. 🖍 Sketch the System from different perspectives

The practice of sketching clarifies the mental model of the system in your mind. It doesn’t have to be a complicated drawing. The router module calls different “views”. Where are the views defined? What do they do? Here’s a quick sketch showing the relationship between the router and views:

What about the relationship between views and components? Find the components that are called in the home view. In your notebook, draw your own diagram showing the relationship between views/home and components/*.

You could also sketch:

• Data Flow Map: Illustrate how data moves through the system
• Component Tree: Show the hierarchy of components
• Dependency Map: Identify which modules depend on each other

Patterns are reusable solutions to common problems.

In the PurpleForest application, there are identifiable patterns. These are rules that the original developers followed when they built the application. By understanding these patterns, you can understand how the application works and how to extend it.

Code Conventions

We can also see regularities in the codebase called conventions. You can derive useful information from these conventions. Write down your answers to the following questions:

Component Creation Pattern

Let’s identify a convention in the Purple Forest application. Read any “createComponent” function in the Purple Forest codebase. In your notebook, write down the general steps this function takes to create a component.

// function name starts with create
// then name of file
// function expects a template (id) and data as arguments {
// first, return if there's no data
// next, clone template to create a fragment
// then, populate the fragment with data
// return fragment
//}

Check your specification against another “createComponent” function. Does the pattern hold?

Why Patterns Matter

Patterns help you:

• Predict how other parts of the system work
• Guide your implementation of new features
• Spot potential problems where patterns are broken

Understanding patterns allows you to chunk🧶🧶 chunkChunking is a way to group information together so it’s easier to remember and understand. information, making complex codebases easier to comprehend.

🧠 Recall that debugging is about forming and testing hypotheses. Each test brings you closer to understanding the system’s intended and actual behaviour.

With the application running, reproduce the issue by creating a bloom with the hashtag #do and navigating to /#/hashtag/do. Open Devtools and trace the request flow, just as we did in Navigation.

Yikes! As soon as we open the Network panel we can see the app is making many many many requests!

Prediction: there’s some kind of loop in the system that’s causing the page to refresh over and over. Explanation: the network panel is showing a lot of requests to the same endpoint.

We can see precisely which files are involved in this request in the call stack. This stack trace allows us to reduce our problem domain to these 5 files.

_apiRequest @ //front-end/lib/api.mjs:33
getBloomsByHashtag @ //front-end/lib/api.mjs:163
hashtagView @ //front-end/views/hashtag.mjs:20
handleRouteChange @ //front-end/lib/router.mjs:24
(anonymous) @ //front-end/index.mjs:44
updateState @ //front-end/lib/state.mjs:26

Remembering what we just learned, Cmd+P and open api.mjs, Cmd+F to jump to _apiRequest. This is a wrapper function that all these endpoints call, so it’s not likely to be the problem if only this one view is refreshing.

1. Read getBloomsByHashtag. Is there a clue in here?
2. What is calling this function? Use fn+Shift+F12 to navigate to hashtagView. Prediction: if we comment out the apiService.getBloomsByHashtag call, the page will stop refreshing. Try it.

This should be a clue.

This is where debugging legacy code can be faster than a greenfield application. This application is working, and other views don’t have this problem. So we can look at other views, and spot the difference. In views/profile.mjs for example, we call the apiService inside a conditional:

// Only fetch profile if we don't have it or if it's incomplete
if (!existingProfile || !existingProfile.recent_blooms) {
  apiService.getProfile(username);
}

1. Hypothesis: The hashtagView is calling apiService.getBloomsByHashtag multiple times.
2. Test: Comment out the apiService.getBloomsByHashtag call in hashtagView.
3. Result: The page stops refreshing… and is also blank.
4. Conclusion: The loop is caused by hashtagView calling apiService.getBloomsByHashtag multiple times.

Uncomment the line and don’t make any further changes to the codebase. Move on to the next step.

Tests are the best documentation for how a system should behave.

Describe the Behaviour, Capture your Understanding

Now we have an understanding of the system, the bug, and the intended behaviour, we need to write a test to capture our understanding. There are some Playwright tests in the codebase already, but no project has complete test coverage for absolutely every eventuality.

Launch the test runner (look in package.json to find the command). Find the file to add your test and describe the behaviour you expect.

📝 Activity: Write a test for the hashtag endpoint

// Given I am logged in
// When I navigate to /front-end/#/hashtag/playwright
// Then the number of requests should be fewer than 4

test("should not make infinite hashtag endpoint requests", async ({ page }) => {
  // ===== ARRANGE
  const requests = [];
  page.on("request", (request) => {
    if (
      request.url().includes(":3000/hashtag/playwright") &&
      request.resourceType() === "fetch"
    ) {
      requests.push(request);
    }
  });
  // ====== ACT
  // When I navigate to the hashtag
  await page.goto("/front-end/#/hashtag/playwright");
  // And I wait a reasonable time for any additional requests
  await page.waitForTimeout(200);

  // ====== ASSERT
  // Then the number of requests should be 1
  expect(requests.length).toEqual(1);
});

Your test should be failing because your system is making too many requests. This is a good thing! It means you have a clear goal for your next step.

The fixing cycle protects against regressions

We have identified our issue and written our test/s. We’ve really done all the hard work already. Fixing the actual code is now simple.

Fix your code!

if (hashtag !== state.currentHashtag) {
  apiService.getBloomsByHashtag(hashtag);
}

✍🏾 Document your fix in your PR message.

Once you have got the entire fix working end to end with tests, open a PR with your changes. In your PR message, write everything that you needed to know to solve this problem. Be good to the reviewer, they’re a good friend of yours.

📅 Schedule a revision

Schedule a revision in your calendar for one week from today to come back and review your own PR.

For Purple Forest, this means:

1. Following the component-based architecture
2. Using the single source of truth pattern for state
3. Extending the API service for data fetching and updates if necessary

In your backlog, you have some more features to add. Let’s do one simple feature extension together. Branch from main to feature/unfollow.

Add an “Unfollow” button to the Profile component. This button should remove the current user from the list of followers. The button should only appear if the current user is following the user.

test("allows unfollowing a user from their profile", async ({ page }) => {
  // Given a profile component sample
  // And I am logged in as sample2
  await loginAsSample2(page);
  // And sample2 is following sample
  await page.goto("/front-end/#/profile/sample");
  await page.click('[data-action="follow"]');

  // When I view the profile component for sample
  // Then I should see a button labeled "Unfollow"
  const unfollowButton = page.locator('[data-action="unfollow"]');
  await expect(unfollowButton).toBeVisible();

  // When I click the "Unfollow" button
  await unfollowButton.click();

  // Then I should no longer be following sample
  const followerCount = page.locator("[data-follower-count]");
  await expect(followerCount).toHaveText("0");
  // And the unfollow button is not visible
  await expect(unfollowButton).toBe("hidden");
});

@app.route("/unfollow/<unfollow_username>", methods=["POST"])
@jwt_required()
def unfollow(unfollow_username):
    username = get_current_user().username

    if unfollow_username not in users:
        return make_response(
            (f"Cannot unfollow {unfollow_username} - user does not exist", 404)
        )

    follows.remove(username, unfollow_username)
    return jsonify(
        {
            "success": True,
        }
    )

✍🏾 Document your feature in your PR message.

Once you have got the entire feature working end to end with tests, open a PR with your changes. In your PR message, write everything that you needed to know to build this feature. Be good to the reviewer, they’re a good friend of yours.

📅 Schedule a revision

Schedule a revision in your calendar for two weeks from today to come back and review your own PR. You might choose to refactor your feature in your review.