Short Units Are Easy to Test

Units encapsulate the application logic of your system, and typically much testing effort is spent on validating the application logic’s correctness. This is because the Java compiler will not detect errors in the application logic automatically, and neither will your editor or IDE (integrated development environment; e.g., Eclipse). Code with a single responsibility is easier to test. In general, short units may do only one thing, while long units do multiple things and tend to have more responsibilities. A unit with one responsibility is easier to test, since it implements a single indivisible task. That allows the test to be isolated (specific to the unit) and simple. Chapter 10 discusses testing in more detail.

Short Units Are Easy to Analyze

It takes less time to read all the code in a short unit in order to analyze how the unit works internally than it does in a long unit. This may not be apparent when you are writing new code, but it makes all the difference when you are modifying existing code. This is not an exceptional situation, since maintenance begins the day after the project is started.

Short Units Are Easy to Reuse

A unit should always be invoked in at least one method (otherwise, the unit is dead code). In a system, you can reuse a unit by invoking it in more than one method. Small units are better candidates for reuse than long units. Long units tend to offer specific details or provide a specific combination of functionalities. As a result, they have more specialized functionality than short units. This makes reuse hard, because it is not very likely that the specific functionality of a long unit is suitable. In contrast, short units tend to be more generic. This makes reuse easier, because it is more likely to fit your needs. Reusing code also helps keep the total code volume low (see Chapter 9).

When Writing a New Unit

Assume you are writing a class that represents a level in JPacman, the codebase we use for a number of examples in this book. See the sidebar “About JPacman” for an introduction to it. This class provides public start and stop methods that are called from buttons in the user interface of the game. A level maintains a list of observers: classes that need to be informed whenever the level has finished.

The most basic version of the start method checks whether the game is already in progress. If so, it silently returns; otherwise, it updates inProgress, a private member to keep track of its state:

public void start() {
    if (inProgress) {
        return;
    }
    inProgress = true;
}

So far our unit contains only four lines of code. At this point, we can add a unit test for our unit. When you use TDD (test-driven development), you already have a unit test at this point. Unit testing is discussed in Chapter 10.

When Extending a Unit with New Functionality

When you extend your system with new functionality, you will see that units start to grow longer. Discipline is required to adhere to a strict size limit. The next thing the start method needs is functionality that updates all observers of the level to inform them about the current state. Here is how that works if we add code that tells all observers the level has been lost if the player has died, and that tells all observers that the level is won if any pellets are left:

public void start() {
    if (inProgress) {
        return;
    }
    inProgress = true;
    // Update observers if player died:
    if (!isAnyPlayerAlive()) {
        for (LevelObserver o : observers) {
            o.levelLost();
        }
    }
    // Update observers if all pellets eaten:
    if (remainingPellets() == 0) {
        for (LevelObserver o : observers) {
            o.levelWon();
        }
    }
}

Adding the code to update observers made our unit grow to 16 lines of code (and 18 lines in total, including the 2 lines that contain comments). After testing the behavior of this new code, you are probably already thinking about the next functionality to implement. However, you need to refactor first to follow the guideline of this chapter.

Using Refactoring Techniques to Apply the Guideline

This section discusses two refactoring techniques to apply the guideline and achieve shorter units of code.

public void start() {
    if (inProgress) {
        return;
    }
    inProgress = true;
    updateObservers();
}

private void updateObservers() {
    // Update observers if player died:
    if (!isAnyPlayerAlive()) {
        for (LevelObserver o : observers) {
            o.levelLost();
        }
    }
    // Update observers if all pellets eaten:
    if (remainingPellets() == 0) {
        for (LevelObserver o : observers) {
            o.levelWon();
        }
    }
}

private void updateObservers() {
     updateObserversPlayerDied();
     updateObserversPelletsEaten();
}

private void updateObserversPlayerDied() {
    if (!isAnyPlayerAlive()) {
        for (LevelObserver o : observers) {
            o.levelLost();
        }
    }
}

private void updateObserversPelletsEaten() {
    if (remainingPellets() == 0) {
        for (LevelObserver o : observers) {
            o.levelWon();
        }
    }
}

public Board createBoard(Square[][] grid) {
    assert grid != null;

    Board board = new Board(grid);

    int width = board.getWidth();
    int height = board.getHeight();
    for (int x = 0; x < width; x++) {
        for (int y = 0; y < height; y++) {
            Square square = grid[x][y];
            for (Direction dir : Direction.values()) {
                int dirX = (width + x + dir.getDeltaX()) % width;
                int dirY = (height + y + dir.getDeltaY()) % height;
                Square neighbour = grid[dirX][dirY];
                square.link(neighbour, dir);
            }
        }
    }

    return board;
}

private void setLink(Square square, Direction dir, int x, int y, int width,
    int height, Square[][] grid) {
    int dirX = (width + x + dir.getDeltaX()) % width;
    int dirY = (height + y + dir.getDeltaY()) % height;
    Square neighbour = grid[dirX][dirY];
    square.link(neighbour, dir);
}

public Board createBoard(Square[][] grid) {
    assert grid != null;

    Board board = new Board(grid);

    int width = board.getWidth();
    int height = board.getHeight();
    for (int x = 0; x < width; x++) {
        for (int y = 0; y < height; y++) {
            Square square = grid[x][y];
            for (Direction dir : Direction.values()) {
                setLink(square, dir, x, y, width, height, grid);
            }
        }
    }

    return board;
}

class BoardCreator {
    private Square[][] grid;
    private Board board;
    private int width;
    private int height;

    BoardCreator(Square[][] grid) {
        assert grid != null;
        this.grid = grid;
        this.board = new Board(grid);
        this.width = board.getWidth();
        this.height = board.getHeight();
    }

    Board create() {
        for (int x = 0; x < width; x++) {
            for (int y = 0; y < height; y++) {
                Square square = grid[x][y];
                for (Direction dir : Direction.values()) {
                    setLink(square, dir, x, y);
                }
            }
        }
        return this.board;
    }

    private void setLink(Square square, Direction dir, int x, int y) {
        int dirX = (width + x + dir.getDeltaX()) % width;
        int dirY = (height + y + dir.getDeltaY()) % height;
        Square neighbour = grid[dirX][dirY];
        square.link(neighbour, dir);
    }
}

public Board createBoard(Square[][] grid) {
    return new BoardCreator(grid).create();
}

Objection: Having More Units Is Bad for Performance

“Writing short units means having more units, and therefore more method calls. That will never perform.”

Indeed, theoretically, there is a performance penalty for having more units. There will be more method invocations (compared to having fewer, longer units). For each invocation, a bit of work needs to be done by the Java Virtual Machine (JVM). In practice, this is almost never a problem. In the worst case, we are talking about microseconds. Unless a unit is executed hundreds of thousands of times in a loop, the performance penalty of a method invocation is not noticeable. Also, the JVM is very good at optimizing the overhead of method invocations.

Except for very specific cases in enterprise software development, you can focus on maintainability without sacrificing performance. An example is when a method is invoked hundreds of thousands of times in the case of certain algorithms. This is probably one of the very few cases in a programmer’s life where you can have your cake and eat it too. We are not saying that there are no performance issues in enterprise software development; however, they seldom, if ever, are caused by excessive method calling.

Objection: Code Is Harder to Read When Spread Out

“Code becomes harder to read when spread out over multiple units.”

Well, psychology says that is not the case. People have a working memory of about seven items, so someone who is reading a unit that is significantly longer than seven lines of code cannot process all of it. The exception is probably the original author of a piece of source code while he or she is working on it (but not a week later).

Guideline Encourages Improper Formatting

“Your guideline encourages improper source code formatting.”

Do not try to comply with guideline by cutting corners in the area of formatting. We are talking about putting multiple statements or multiple curly brackets on one line. It makes the code slightly harder to read and thus decreases its maintainability. Resist the temptation to do so.

Consider what purpose the guideline really serves. We simply cannot leave unit length unconstrained. That would be akin to removing speed limits in traffic because they discourage being on time. It is perfectly possible to obey speed limits and arrive on time: just leave home a bit earlier. It is equally possible to write short units. Our experience is that 15 lines of properly formatted code is enough to write useful units.

As proof, Table 2-1 presents some data from a typical Java 2 Enterprise Edition system, consisting of Java source files but also some XSD and XSLT. The system, currently in production at a SIG client, provides reporting functionality for its owner. The Java part consists of about 28,000 lines of code (a medium-sized system). Of these 28,000 lines of code, just over 17,000 lines are in units. There are just over 3,000 units in this codebase.

Out of the 3,220 units in this system, 3,071 (95.4%) are at most 15 lines of code, while 149 units (4.6% of all units) are longer. This shows that it is very possible in practice to write short units—at least for a vast majority of units.

This Unit Is Impossible to Split Up

“My unit really cannot be split up.”

Sometimes, splitting a method is indeed difficult. Take, for instance, a properly formatted switch statement in Java. For each case of the switch statement, there is a line for the case itself, at least one line to do anything useful, and a line for the break statement. So, anything beyond four cases becomes very hard to fit into 15 lines of code, and a case statement cannot be split. In Chapter 3, we present some guidelines on how to deal specifically with switch statements.

However, it is true that sometimes a source code statement simply cannot be split. A typical example in enterprise software is SQL query construction. Consider the following example (adapted from a real-world system analyzed by the authors of this book):

public static void printDepartmentEmployees(String department) {
    Query q = new Query();
    for (Employee e : q.addColumn("FamilyName")
        .addColumn("Initials")
        .addColumn("GivenName")
        .addColumn("AddressLine1")
        .addColumn("ZIPcode")
        .addColumn("City")
        .addTable("EMPLOYEES")
        .addWhere("EmployeeDep='" + department + "'")
        .execute()) {
        System.out.println("<div name='addressDiv'" + e.getFamilyName()
            + ", " + e.getInitials() + "<br />" + e.getAddressLine1()
            + "<br />" + e.getZipCode() + e.getCity() + "</div>");
    }
}

This example has 16 lines of code. However, there are just three statements. The second statement contains an expression that spans nine lines. Indeed, you cannot extract just this statement; neither the Extract Method nor the Replace Method with Method Object technique is applicable, at least not directly. However, the nine-line expression starting with q.addColumn("FamilyName") can be extracted into a new method. But before doing that (and seeing the newly created method grow to over 15 lines when the query gets more complex in the future), rethink the architecture. Is it wise to create a SQL query piece by piece as in this snippet? Should the HTML markup really appear here? A templating solution such as JSP or JSF may be more suitable for the job at hand.

So, if you are faced with a unit that seems impossible to refactor, do not ignore it and move on to another programming task, but indeed raise the issue with your team members and team lead.

There Is No Visible Advantage in Splitting Units

“Putting code in doSomethingOne, doSomethingTwo, doSomethingThree has no benefit over putting the same code all together in one long doSomething.”

Actually, it does, provided you choose better names than doSomethingOne, doSomethingTwo, and so on. Each of the shorter units is, on its own, easier to understand than the long doSomething. More importantly, you may not even need to consider all the parts, especially since each of the method names, when chosen carefully, serves as documentation indicating what the unit of code is supposed to do. Moreover, the long doSomething typically will combine multiple tasks. That means that you can only reuse doSomething if you need the exact same combination. Most likely, you can reuse each of doSomethingOne, doSomethingTwo, and so on much more easily.