You must be careful, however, that the cost of these defect prevention practices does not become excessive. That would introduce a different type of waste – non-value adding process. The waterfall method of software development is an example of this. One of the principles behind waterfall is that careful requirements analysis and design will minimize downstream defects during coding and testing. Put another way, it is a good idea to understand what you need to build before you start building it. The problems with waterfall arise from going to extremes in applying this principle. Requirements analysis is done up front for the entire project as a big batch based on the theory that it minimizes rework due to future change, but in reality the constant pace of requirement changes plus the learning that occurs throughout the project will result in increasing amounts of change the longer the time spent doing requirements. In contrast, Scrum and Kanban apply this principle using a balanced approach – project level requirements are done at a high level, and the more detailed analysis is done on individual user stories just prior to implementing them. (See for example the article Scrum and CMMI – Going from Good to Great: are you ready-ready to be done-done?.)

In order to effectively adopt a defect prevention practice two pieces of information are needed:

1. Specific, actionable steps to apply the practice.
2. The expected benefit. What categories of defects does the practice intend to prevent? This helps determine when to apply the practice and helps to evaluate it after adoption to assess its effectiveness.

If we consider the idea of careful requirements analysis and design mentioned above as a prevention practice, the benefits are fairly clear - prevent requirement and design based errors - but specific actionable steps are missing so it does not qualify. (In fact, this is one of the contributing factors why waterfall projects can end up in the analysis paralysis anti-pattern.)

Now that the groundwork has been laid I can present some specific defect prevention practices. This is not a comprehensive list – many other practices are possible. The practices I have chosen to discuss are ones that I have used and am confident that they work.

Use Understood Methods Rule

The basic formulation of the rule is quite simple: when coding a method only invoke other methods whose behavior you clearly understand and are confident will work the way you want. I have written a separate article providing specific guidance on how to apply this rule.

This practice generally aims to prevent interface errors - which I define generally as defects between two separate pieces of code. Research suggests that a significant proportion of defects are due to these kinds of errors (See for example the paper An Empirical Study of Software Interface Faults.)

I find this rule particularly valuable when applied to the invocation of methods between classes and especially between components. In this case it helps prevent integration errors which are usually not caught by unit testing.

Design by Contract

The idea of design by contract is to precisely specify the behavior of methods to help ensure that they are invoked correctly by callers and that the callers receive the results they are expecting. This is done by precisely specifying the preconditions and postconditions of methods. The chief proponent of design by contract is Bertrand Meyer, whose book Object-Oriented Software Construction is a classic on the topic.

Method preconditions are conditions that must be true in order for the method to successfully execute and fulfill its postconditions. Preconditions are most commonly applied to method arguments. For example, a method to convert a string to a date might have the precondition that the string argument must not be null. Preconditions can also be applied to the state within the class or even external state. For example, a method to delete a particular object from the database might have the precondition that the object exists within the database.

Method postconditions are conditions that the method guarantees to be true after execution, assuming the preconditions are met. Postconditions are most commonly applied to the return value of methods, but like preconditions can also be applied to the state within the class or external state. Returning to the example of a method that converts a string to a date, such a method could have two postconditions. First, that the method will return a corresponding date object that is not null if the input is a string in a valid date format, and second that the method will throw a specified exception if the input does not correspond to a valid date format.

The combination of preconditions and postconditions forms in essence a contract between the method and its caller. The caller promises to fulfill the preconditions in exchange for the method guaranteeing that the postconditions will be met.

Despite the fact that the name of this practice contains the word "design", this approach does not require a separate up-front design of each method. The goal is to have a clear specification of behavior once the method is finished – how you arrive at it is not important to this practice. I tend to start with an initial idea for a method’s contract that I evolve as I write tests and implement the method’s logic using test-driven development.

There are several options for specifying pre- and post- conditions. Some teams rely solely on their automated unit tests to serve as the specification, but I prefer a more concise specification provided as part of the method definition. In Java I typically use JavaDoc to document pre- and post- conditions and programmatically check argument preconditions at the start of the method. I typically formally specify pre- and post- conditions only on methods that are intended for use by other classes or components. In Java, this is typically public and protected methods of interfaces and classes.

This practice is very closely related to the Use Understood Methods Rule, and they go hand-in-hand. Knowing a method’s pre- and post- conditions is necessary to fully understanding it. As I stated above, I tend to only apply formal design by contract to methods intended for use outside the class in question, which means this practice is really aimed at preventing integration defects.

Defensive Coding

Defensive coding is named after the practice of defensive driving and is based on the same mindset of expecting problems to occur and actively taking precautions to avoid them. Defensive coding is applied by adopting a language-specific set of idioms that minimize or prevent common coding errors when using the language. These idioms are often reflected in coding standards.

Here are some examples of defensive coding idioms for Java:

• When comparing if a variable is equal to a constant, put the constant first. This avoids a potential null-pointer exception (if the variable is null) by invoking the equals() method on the constant, which is never null.

  public boolean isAdmin(String userId) {
    String constant = "admin";
    return constant.equals(userId); // Instead of userId.equals(constant)
  }
  

• Always use braces to define a block of code for an if, else, while, for, or do statement, even if the block contains only a single line of code. This avoids the problem of later adding a second line of code indented to the same level as the first and mistakenly thinking it will invoked as part of the block.

  public void addOptions(String userId) {
    if (isAdmin(userId)) {
      addAdminOptions();
    } else {
      addRegularUserOptions();
    }
  }
  

• Use the Java 5 for-each construct rather than using a loop index variable to manually iterate through a list. This avoids the problem of having an off-by-one error in constructing the loop.

  public void processOptions(List options) {
    for (Option option : options) {
      option.process();
    }
  }
  

Defensive coding aims to minimize coding errors, both at the time of coding and in the future when the code is being modified by others. While these types of errors are typically easily detected by unit testing, I find that using these idioms (after the initial adoption) takes virtually no effort or thought on my part, making them literally a no-brainer to use.

Example-Based Requirements

The idea behind this practice is to express requirements as much as possible in terms of concrete examples rather than the generalized wording typically used in use cases and lists of business rules which is almost always ambiguous. I have written a separate article providing further details on example-based requirements which includes a specific example. :)

The practice of example-based requirements aims at minimizing requirement errors, particularly errors due to misunderstanding or misinterpreting. The examples should also be used as acceptance test cases, in which case they help detect design or coding errors (although unit tests should identify most of these first).

Conclusion

I encourage you to choose one or more of these practices to adopt in your current development work. There will be extra effort initially to understand and become comfortable with a given practice, but this will decline over time as you achieve mastery of it.

The idea of to do comments really only makes sense with the proper tooling. The Eclipse integrated development environment calls them task tags, and supports providing any number of custom identifiers that when found in a comment will cause Eclipse to add that comment into its Task view. The default identifiers that Eclipse ships with include "FIXME" and "TODO". You can then browse the task view, sorting or filtering the tasks by various criteria, to see the outstanding work. Continuous integration servers such as Hudson running the Task Scanner plugin can produce statistics, reports, and graphs of the outstanding tasks in a code base.

Why use to do comments?

When doing my own coding, I use to do comments when ideas come to me regarding code I need to write or special cases I need to handle that are separate from what I am coding right now (usually in order to get the current test to pass, via test-driven development). Writing the idea down gets it out of my mind and out of my way. Using a to do tag reassures me that it will not be forgotten: part of my definition of done is to ensure that there are no to do comments remaining in the code.

When looking at code written by other team members, I want to be able to quickly tell what state the code is in – is it completely finished, or is it a work-in-progress, with scenarios or requirements left to be handled? The reason I care is that if I think the code is supposed to be finished, and see issues or outstanding work, then I will raise the issue(s) with the developer. Fairly often when I have done this in the past, the developer reassures me that they were already aware of the issue and would resolve it. That is usually when I recommend the use of to do tags as a communications mechanism to the rest of the team as to the status of the code, especially if someone else had to take over working on that code. And as often as not, unrecorded issues that developers say they are aware of and will resolve later end up being forgotten and left unresolved.

I hope I have convinced you of the value of using to do comments. Please leave a comment and let me know what you think about the practice.

I was upgrading a Java web application to WebSphere server version 6.1 and as the first step I switched the development environment to Rational Application Developer version 7. With the new IDE came an improved compiler that reported additional warnings, so it didn't surprise me to see hundreds of new warnings. It is a standard practice of mine to eliminate warnings, even harmless ones, since a significant warning can easily be missed if harmless warnings are allowed to remain. As I worked my way through the warnings, I came across a new one I did not recognize: "Finally block does not complete normally". A simplified version of the code producing this warning is shown below:

  boolean performBusinessOperation() {
    boolean operationResult = false;
    try {
      // Perform some business logic...
      operationResult = true;
    } catch (IllegalStateException e) {
      // Handle this exception..
      operationResult = false;
    } catch (IllegalArgumentException e) {
      // Handle this exception...
      operationResult = false;
    } finally {
      // Common cleanup...
      // Following line produces warning
      // "Finally block does not complete normally"
      return operationResult;
    }
  }

This was not code I had written, so I spent some time trying to figure out the reason for the warning. In Java, the finally block is guaranteed to be executed after the contained try block finishes execution, even if an exception is thrown within the try block. If an exception is thrown and not caught within a function, the exception is propagated up the call stack until it encounters an appropriate catch block. But in this particular case within the performBusinessOperation method, if an uncaught exception is thrown, the finally block will run and perform the return statement. So which will win - the exception or the return? I was not sure, which in my mind explained the warning - it is bad practice to write code with unclear behavior. So I fixed the code by moving the return statement outside the finally block and moved on to the next warning.

Once I was finished eliminating warnings, I ran the entire suite of automated unit tests. To my surprise, I had a few failures. When I tracked down the offending code, I was surprised to see that it was my fix for the "Finally block does not complete normally" warning that broke the tests. How could that be? After further tracing and debugging, I finally found the reason: the unit test incorrectly invoked the method in question, causing it to throw a NullPointerException from within the try block. Having the return statement within the finally block apparently was causing the exception to be silently discarded. I found this shocking. This is dangerous behavior for a language, and I had problems believing that was actually the case. So I wrote a quick unit test for verification, shown below.

public class ReturnInFinallyBlockExample
  extends junit.framework.TestCase
{
  @SuppressWarnings("finally")
  private boolean isReturnWithinFinally() {
    try {
      if (true) throw new RuntimeException();
    } finally {
      return true; // This hides the exception
    }
  }

  private boolean isReturnOutsideFinally() {
    try {
      if (true) throw new RuntimeException();
    } finally {
      // Return outside finally block.
    }
    return true;
  }

  public void testReturnFromFinallyBlockWithUnhandledException() {
    assertTrue(isReturnWithinFinally());
    try {
      isReturnOutsideFinally();
      fail("Expect exception");
    } catch (RuntimeException e) {
      // Expected case.
    }
  }
}

This test case passes, demonstrating that the uncaught exception within the try block is silently discarded if the return statement is within the finally block. Note my use of the Java 5 annotation @SuppressWarnings("finally") in order to stop the compiler from reporting the "Finally block does not complete normally" warning for this example.

Perhaps I should have been less surprised by this behavior in Java given that I was already aware of another suboptimal situation regarding Java exception handling in finally blocks: if an uncaught exception is thrown in a try block and then another exception is thrown in the finally block, it will be the second exception that is propagated out of the method. The first exception will be silently lost. The following test case demonstrates this behavior:

public class ExceptionInFinallyBlockExample
  extends junit.framework.TestCase
{
  private void haveExceptionInFinallyBlock() {
    try {
      if (true) throw new IllegalArgumentException();
    } finally {
      if (true) throw new NullPointerException();
    }
  }
  public void testHaveExceptionInFinallyBlock() {
    try {
      haveExceptionInFinallyBlock();
      fail("Expect exception");
    } catch (NullPointerException e) {
      // Expected case.
    }
  }
}

Ignoring errors is dangerous, as I have discussed in my article on Error Handling and Reliability. So I strongly feel that the Java language should have prohibited return statements in finally blocks. Fortunately, modern Java IDEs like Eclipse can make up for this shortcoming by allowing you to flag this code construct as an error rather than a warning.

The source code listed in this article is provided in the Java Examples project which can be downloaded from the Software page.

As a professional software developer, I believe it is important to be aware of and able to justify our practices. Here are my reasons for declaring local variables at their point of use:

1. Code is easier to read. There are fewer lines of codes, which means it is easier for a single method to fit entirely on the screen. When I see the local variable first being used, I can see what type it is since the declaration is right there, as opposed to having to scroll to the start of the method.
2. Code is easier to write. When adding some code involving a new local variable, declaring the local variable at the cursor is much easier than scrolling back to the top of the method to add it.
3. The inline local variable refactoring in Eclipse can be performed. Eclipse does not allow this refactoring when the variable is declared separately and not initialized, or is initialized twice.

When writing this article, I had some additional justifications for my approach that turned out to be invalid. I thought that declaring local variables earlier than their point of use would make it more difficult to perform the extract method refactoring in Eclipse, but I checked and it doesn't make a difference. I also thought that my approach is more consistent with the Sun Java code conventions, but I was wrong about that as well. The relevant lines from this code conventions document are: "Try to initialize local variables where they're declared." and "Put declarations only at the beginning of blocks. Don't wait to declare variables until their first use." Neither approach in this article is fully consistent with the Sun conventions.

Below are code examples of the two approachs.

Example 1: Method with local variable declarations at point of use.

public static Object clone(Serializable target) {
  Assert.notNull("target", target);

  try {
    ByteArrayOutputStream byteOutputStream = new ByteArrayOutputStream();
    ObjectOutputStream objectOutputer = new ObjectOutputStream(byteOutputStream);
    objectOutputer.writeObject(target);
    objectOutputer.close();
    byteOutputStream.close();

    ByteArrayInputStream byteInputStream = new ByteArrayInputStream(
      byteOutputStream.toByteArray());
    ObjectInputStream objectInputer = new ObjectInputStream(byteInputStream);
    Object clonedTarget = objectInputer.readObject();
    return clonedTarget;
  } catch (Exception e) {
    throw new RuntimeException("Error cloning object via serialization.", e);
  }
}

Example 2: Revision of the method in example 1 with all local variables declared at the start of the method:

public static Object clone(Serializable target) {
  ByteArrayOutputStream byteOutputStream;
  ObjectOutputStream objectOutputer;
  ByteArrayInputStream byteInputStream;
  ObjectInputStream objectInputer;
  Object clonedTarget;

  try {
    byteOutputStream = new ByteArrayOutputStream();
    objectOutputer = new ObjectOutputStream(byteOutputStream);
    objectOutputer.writeObject(target);
    objectOutputer.close();
    byteOutputStream.close();

    byteInputStream = new ByteArrayInputStream(
      byteOutputStream.toByteArray());
    objectInputer = new ObjectInputStream(byteInputStream);
    clonedTarget = objectInputer.readObject();
    return clonedTarget;
  } catch (Exception e) {
    throw new RuntimeException("Error cloning object via serialization.", e);
  }
}

What is your preference?