bookmark_borderWorking 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:

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
	}

}

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?

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 {

What about this?

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 {

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

	public void movePlayerAmountRolledAndAskQuestionOrWhenInPenaltyBoxIfUnevenRolledGetOutOfPenaltyBox(int roll) {

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:

	if (rolled % 2 != 0) {

Which you could turn into (extract into variable):

	boolean isUnevenRoll = roll % 2 != 0;
	if (isUnevenRoll) {

Or extract method:

	if (isUneven(roll)) {

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:

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 {

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!

bookmark_borderRegression – Lets stop it!

I hate it.

You change something and you can’t tell if your change broke something in the system.

If you’re lucky, you did not break anything. Or nobody noticed it.
Next to that, on the same scale of luck, the potential bugs are found in the manual testing phase.

But often there is no time to do all the regression testing by hand. It will take days and days, and the change you made looked so insignificant. It should go live. What could possibly go wrong?.

Then it happens. You’re live, your changes work, but the inevitable happens. Regression!

Of course, this has to be fixed. We can’t let our customers have a product with new features while the features of the previous version(s) are broken.

And so the patching process begins.

I call it patching, because often you are not done with one patch. While you were working hard to get the first patch live, other regression bugs are found and need to be patched asap as well! And so you end up with a few patches. You could be done with with a few patch releases. But it could easily extend ten-fold.

This process is very stressful for the customer and the development team. As the team is working to get these patches out soon, the customer is unhappy with his ‘broken system’. Even worse, once a few bugs are found, more testing is done on the live system to make sure everything still works, and more regression bugs poor in, adding up to the stress. To the development team it begins to look like…

From the customer’s point of view, it looks like the team working on the product is not in control. It is as if the team does not seem to know what they are doing. To them their product, which seemed rock solid at start, is degrading to a house of cards.

You can debate about high and low impact issues, and the matter of urgency to fix these issues. The perception of the customer is likely to be the same, regardless.

This is how I see it:

It is us developers who are responsible for letting regression happen.

Not testers.
Not project managers.
Not stakeholders.
Not the customer.

It is us and us alone.

We write the code, we change the code, we are in control of the code (at least we should be!).

Even if you happened to be depending on a third-party system, it is your job to keep an eye out on that system. Verify that it behaves as you would expect it to. Why? Your system depends on the behaviour of another system, trusting that this behaviour does not change is not enough. You have to be *sure*.

Its all about attitude
Do you always deal with regression bugs after each release?

Stop accepting it, it is not normal.

Rather, start thinking about how you can prevent this. Don’t look how other people could prevent this. Think of what you could do right now. There are many ways to reduce the amount of regression bugs. For instance: add tests before changing any code. Fixate the behavior with black box tests. When you refactor, keep running your tests so you know you did not break existing behaviour. Add new tests for new features you introduce. Create a test suite that you can trust. Make integration tests. Is it hard to write tests? Make it easier. Don’t back away from the code, it is your code and you should be in control.

Besides the code, improve your own skills. Start reading about how to deal with legacy code. Attend a legacy code retreat to hone your skills. Practice, practice, practice! Get better.

Reap what you sow in your daily work.

But isn’t the whole team responsible?
Ah, of course! But does that mean that you, as a developer can now do less? Would it be okay in a team to not test, because you have testers? (“its their job right?”).

In a team we all have our strengths and weaknesses.

We understand code, and we can change code. No other role in your team is responsible for understanding the code then you. Being in a team does not make you less responsible.

Again, it is all about attitude. Stand for your craft, deliver high quality work and make sure the system is in check. It should be you who controls the system.

Attitude, again
There are developers out there who really think they know everything of the system. And to be honest, I once had a time where I always knew what changes had impact and what I could do. And even though I was right about the impact on changes…

…I was at least wrong as many times as I was right.

But sometimes it is not just being over-confident. Sometimes it is being ignorant, or even arrogant.

Please, don’t be like this guy…

Just because it is hard, doesn’t mean you shouldn’t do it
Regression is a pain. It can be dealt with.

It is not easy.

You will not completely eliminate regression bugs. But with the correct mindset, tools and safety-net(s), you will greatly reduce the amount of regression bugs.

It is necessary. Just do it. For the love of our (your!) craft, do it, for everyone who depends on us:

The customer.
The stakeholders.
The project managers.
Yes, even the testers.