Working with legacy code – how to start & reveal intent

Recently I posted my opinion about regression. Regression bugs are likely to occur on projects with a lot of legacy code. I consider legacy code as untested code.

At the legacy coderetreat we used a small codebase (you can find it here). With that codebase we exercised in sessions to improve the code. The nice thing is that this is very similar with your daily job. You open up a project and you have to make changes in code you haven’t seen before and do not understand.

In order to get a better understanding you can use various techniques. I have practiced them with the legacy coderetreat and also applied this at work. In this blog post I’d like to share my experiences. Btw: If you haven’t experienced a coderetreat yet, join one. Just like kata’s, they are really worth your time (and more fun)!

Step 1: Get a sense of what is happening
Before we can do anything, we have to understand what we need to change and how it has impact on the system. One way to find out is to simply execute the code. You could just run the application, or… you could try to write a simple unit test executing the ‘main method’ you think that should be ran. Poke around with the parameters, and see what happens.

I prefer writing Characterization tests. The benefit is that while I am trying to understand what is happening, I am also building a safety net. Writing a Characterization test goes like this:
– create new test
– do some setup
– run specific piece of code (method) you want to try out
– check outcome / read state
– create assertion to make it pass with the outcome

When I don’t know what it actually does, I call my tests ‘monkey‘. Once I know the behavior with the given input, I rename the test to what the behavior is. Example:

[sourcecode language=”java”]
package com.adaptionsoft.games.uglytrivia;

import org.junit.Assert;
import org.junit.Test;

import static org.hamcrest.core.Is.*;
import static org.junit.Assert.*;

public class GameTest {

@Test
public void isPlayableReturnsFalseWhenInitialized() {
Game game = new Game();
assertThat(game.isPlayable(), is(false));
}

@Test
public void isPlayableReturnsTrueWithTwoPlayers() {
Game game = new Game();
game.add("Stefan");
game.add("Niels");
assertThat(game.isPlayable(), is(true));
}

@Test
public void monkey() {
Game game = new Game();
game.add("Stefan");
game.add("Niels");
game.roll(5);
// no idea yet what happens, need to look into roll method to get a clue
}

}
[/sourcecode]

So this gives me a rough idea what is happening, and it gives me a suite of tests.

It is important that you focus on black box tests. Try not to bother about the internals. If you are deep-stubbing in your test setup then try to think of a different way to approach the problem. Sometimes it is not possible to do black box testing, only then you need to do white box testing. In these cases deep-stubbing is often needed. Deep stubbing indicates a design problem: your class is bothered with internal states of other objects. You can reduce this by applying Tell Don’t Ask.

Step 2: Reveal intent.
This is even less invasive (actually it is not invasive at all if done well) than the small refactorings I have blogged about in the past.

To reveal intent:
– go through the code, find magic numbers and strings. Introduce constants for them with descriptive names
– find method names that do not describe well their behavior, and rename them. Try to keep the name about behavior, and if it does more then one thing, concate these behaviors with “And”.
– do the same for variables

This may sound trivial, but it really enhances the understandability of the code. As a bonus your understanding of the code is increased a lot, and all you did was renaming things and perhaps introduced a few constants. Let me show you how much it matters:

Can you find things to improve in this code?
[sourcecode language=”java”]
if (roll % 2 != 0) {
isGettingOutOfPenaltyBox = true;

System.out.println(players.get(currentPlayer) + " is getting out of the penalty box");
places[currentPlayer] = places[currentPlayer] + roll;
if (places[currentPlayer] > 11) places[currentPlayer] = places[currentPlayer] – 12;

System.out.println(players.get(currentPlayer)
+ "’s new location is "
+ places[currentPlayer]);
System.out.println("The category is " + currentCategory());
askQuestion();
} else {
[/sourcecode]

What about this?
[sourcecode language=”java”]
if (roll % 2 != 0) {
isGettingOutOfPenaltyBox = true;

System.out.println(players.get(currentPlayer) + " is getting out of the penalty box");
places[currentPlayer] = places[currentPlayer] + roll;
if (places[currentPlayer] > PLACE_BEFORE_STARTING_PLACE) places[currentPlayer] = places[currentPlayer] – MAX_PLACES;

System.out.println(players.get(currentPlayer)
+ "’s new location is "
+ places[currentPlayer]);
System.out.println("The category is " + getCurrentCategoryForCurrentPlayerOnPlace());
askQuestionAndRemoveFromQuestionFromDeck();
} else {
[/sourcecode]

This method name is called “roll” initially. If you would sum up all its behavior it would be more like:

[sourcecode language=”java”]
public void movePlayerAmountRolledAndAskQuestionOrWhenInPenaltyBoxIfUnevenRolledGetOutOfPenaltyBox(int roll) {
[/sourcecode]

Who would ever accept such a long method name? I would, but it should trigger something. This method name tells you there is way too much going on in one place. And, since the method is public, we communicate to other classes what this thing is doing.

It is ok to rename multiple times. The longer you work with the code, the better you understand it. When the method names do not reflect their real intent, make it clearer and improve their names. Communicating what the code actually *does* is important, make it explicit. especially if the method name violates conventions (ie, a getSomething() method that is not getting a property, but does more than that.)

It is very tempting to extract expressions and methods
Before you do this. Make sure you have the Characterization tests and integration tests in place. The tests will tell you if you have broken something while refactoring using extract method or extract conditions into variables. Yes, even such small refactoring’s could cause bugs.

Here an example, take this expression:
[sourcecode language=”java”]
if (rolled % 2 != 0) {
[/sourcecode]

Which you could turn into (extract into variable):

[sourcecode language=”java”]
boolean isUnevenRoll = roll % 2 != 0;
if (isUnevenRoll) {
[/sourcecode]

Or extract method:

[sourcecode language=”java”]
if (isUneven(roll)) {
[/sourcecode]

I prefer (automated!) extract method over extracting into variables. The main reason is that extracting into methods introduce very small pieces of code that you can re-use. You could eventually even find that the methods are not particularly bound to the current class’ behavior and move them out of this class into a new class. With variables this is much harder to see and refactor.

With these two steps, we could have brought the code we had earlier into a state like this:

[sourcecode language=”java”]
if (isUneven(roll)) {
isGettingOutOfPenaltyBox = true;

System.out.println(getCurrentPlayer() + " is getting out of the penalty box");
moveCurrentPlayer(roll);

System.out.println(getCurrentPlayer()
+ "’s new location is "
+ places[currentPlayer]);
System.out.println("The category is " + getCurrentCategoryForCurrentPlayerOnPlace());
askQuestionAndRemoveFromQuestionFromDeck();
} else {
[/sourcecode]

Conclusion
When working with legacy code, it is of importance to understand the code before making changes. In order to understand the code we can use introduce constants or rename methods to make the code reveal its intent. Using Characterization tests we can fixate the current behavior and label it in our tests names. Then, once we have this test suite, we can start using small refactoring’s like extract method or extract variable to make conditionals reveal their intent.

When creating a test suite, creating mostly black box tests will help us in the future when refactoring opposed to white box tests. Sometimes white box tests cannot be avoided.

Without any tests we can already have more insight in what is happening. With a test suite we can more safely start refactoring.

More about coderetreats
I have been greatly inspired by the legacy code retreat day, where we could experiment more in our spare time. Just like the previous time I have learned a lot, and I am convinced that others will benefit from this as well. Therefor I have decided to lend a hand and offer to organize and facilitate a coderetreat myself at the end of this year. Stay tuned!

7 comments

  1. Great post!
    I recognize all the steps. Some steps I even use because of the boy scout rule.

    However I think that legacy code is more then untested code. In my view legacy code is also with code smells, design flaws and not according best practices.

    1. Thanks! Yes, these steps are equally important in tested code (which would be in this definition not-legacy-code). I understand why you would call code with code smells, design flaws etc legacy code, however with tests you would be able to change that and have certainty about the outcome. Perhaps we should have some levels of legacy code, where un-tested code is 100% legacy, tested code full of design flaws and code smells 50% legacy? 😉

      1. I don’t agree 🙂

        Legacy code is legacy code but with tests you can refactor safely. But that also depends on the quality of the tests.

        1. Legacy code = legacy code is a cyclic reference, please elaborate. I think adding more terms like ‘code smells and design flaws’ makes the term ‘legacy code’ too broad for interpretation. What one calls a design flaw, another could call intentional. While code not under test is in any way dangerous to touch. I agree about the quality of tests though, and I believe black box tests should be preferred over white box tests so you can refactor and you’re not too much constrained by the internals, breaking all your fragile white box tests 🙂

  2. What I actually meant is that I don’t see any degree in legacy code. Legacy is bad code and I mentioned a couple of things why it can be bad code. Yes, you can argue about the intentions of the code but a real craftsmen can recognize legacy code directly. In most cases you want to do something about legacy code and the first step is to write tests if they don’t existst or add more tests so you are comfortable if you are going to refactor.

    Your definition of legacy code doesn’t cover everything. Recently I read a tweet from @adibolb who was doing a TDD as if you meant it workshop/coderetreat and said that he already saw some legacy code. So there were tests but still legacy code was written. If someone says that it isn’t legacy code because there are tests then how are you going him/her to convince that it is? 😉

    1. I’ve thought about this a bit, and I believe the following:
      Code that is well structured, free of any design smells and whatever, but without tests is still considered ‘bad’ code. Bad because there are no tests to verify the behavior of the code, so changes made to the system cannot be verified, hence regression is iminant. (no safety net)

      Code that is badly structured, and has a lot of tests around them is also bad. I think you’re right by saying that simply having tests is not enough to make it good code. It has one advantage over the “good code without tests” variant. You can make changes to the code, and verify its behavior. Refactoring should be easier (I know, it depends on the type and amount of tests).

      In both cases it is bad. Probably the ‘best code’ is well structured and well covered with tests.

      The term ‘legacy code’ is ambigious. Some people say legacy because, they haven’t written it. Others say it because it is bad structured, and even others say it because it has no tests. In general it is code ‘that is hard to change’.

      About convincing people about legacy code. I would rather ask, why would I need to convince people in the first place? I think we know what legacy is, once we need to make a change in that code. When it is hard to do (wether it is due bad code, or no tests telling us if we did not break anything), we most of the time consider this ‘legacy’.

Leave a Reply

Your email address will not be published. Required fields are marked *