Using Java to Mark Known Bugs

November 3rd, 2008 Zack Roadhouse Posted in Java | 2 Comments »

Many months ago we embarked on a long term development project where we needed to re-factor large amounts of our existing code base to handle some new features. This work required modifying the code to use the type safe ID pattern Graham described in a previous post and a special context object that help connect the various objects together.

Due to the size of the code base, this wasn’t something that we could easily do in one go. We needed an incremental approach that would allow us to gradually evolve the code base in the correct direction over multiple development cycles.  This article describes a technique that we used to track the places that were broken by the initial re-factoring and thus allow us to update the code in bits and pieces.

In my experience, it is quite common to see the following well intended comments in code:

	// BUGBUG: the following section of code might not handle situation X

or:

	// TODO: Add in error handling here

or:

	// This next section doesn't work so i'll just comment it out
	/*
	someNonFunctionalCode();
	*/

Many IDEs (including my current tool of choice — Eclipse) can track these comments and place warning markers in the code in the project explorer and in the editor. It’s also possible to count these markers using grep and friends. For our purposes we needed something that we could track even more easily and could provide additional information about the issue. Therefore we added a bug marker class that is similar to the following (we use JIRA to track our issues, thus the JIRA specific terms in the code):

import org.apache.log4j.Logger;

public class BugMarker {
    private static final Logger logger = Logger.getLogger(BugMarker.class);

    public static void todoNeedsIssue(String comment) {
        logger.warn("BugMarker! (needs issue) " + comment);
    }

    public static void todo(String issueId) {
        logger.warn("BugMarker! JIRA Issue ID: " + issueId);
    }

    public static UnsupportedOperationException todoDisabled(String issueId) {
        todo(issueId);
        return new UnsupportedOperationException(issueId);
    }
}

Using BugMarker, our earlier examples might become:

	BugMarker.todoNeedsIssue("the following section of code might not handle situation X");

and:

	BugMarker.todo("APP-1241");

and:

	throw BugMarker.todoDisabled("APP-2234");
	// Commenting out unreachable code
	/*
	someNonFunctionalCode();
	*/

The first form present here (todoNeedIssue) is a logical step forward from the bug comments because the bug comment appears in a warning log each time it is executed. This keeps the bug visible to the developers and testers. It represents an evolutionary step here — it’s traceable using Java tools but isn’t visible in the issue tracking system. We usually use this when pausing to file the JIRA issue would break our concentration for the task at hand. Generally, it’s best to come back through before submitting the code to source control to convert these to the next form.

The second form (todo) is preferable because then we can be sure that the defect is also being tracked in JIRA and can be planned for during the development cycle triage. The comment in the code can become the title of the JIRA issue (we mostly use the “Task” issue type for this purpose) and the developer can provide extra commentary as needed without modifying the source. It’s also possible to search the code using the issue ID and find the bug markers, or to look up the issue when reading through the code.

The third form (todoDisabled) is used for situations where you actually want the code to fail with an explicit exception instead of continuing to execute (and possible corrupting data in the process).

Because the bug marker is written it Java, it’s possible to use the powerful Java parsing and dependency mechanisms built into modern IDEs to track code problems. This is similar to the way in which using GWT simplifies development of AJAX applications by harnessing the power of the Java tool chain to managed abstraction, dependencies, and refactoring. As developers fix the code and remove the bug markers in the course of other development, they can search the issue tracking system and also close out the related JIRA issue.

Another benefit of using a bug marker is related to improving visibility into the development process of a project. Using bug marker with the issue ID form connects bugs as developers discover them directly to the issue management system. The markers are easy to count and can be used as a metric to measure progress with the goal of reducing zero bug markers in the shipping code.

Hopefully you’ll find this technique either directly applicable to your project or it will inspire other ideas to improve the quality of your code.