FindBugs: make your code better with the CheckReturnValue Annotation

I decided to take a look at FindBugs recently, and used my DirectJNgine project as a testbed. Even though torture testing DJN with FindBugs made me make some changes to it, I just found a bug (thankfully, one that will arise so rarely I doubt any DJN user will ever come across it). Here is the code:

file.delete();
if( logger.isDebugEnabled() ) {
  logger.debug( "Api file deleted: '" + file.getAbsolutePath() + "'");
}

And here is the fix:

if( !file.delete() ) {
  throw new IOException( "Unable to delete " + fullFileName);
}
if( logger.isDebugEnabled() ) {
  logger.debug( "Api file deleted: '" + file.getAbsolutePath() + "'");
}

I just forgot to check the value returned by delete, because I assumed inadvertently that file.delete would raise an IOException. But it just returns a boolean value telling you whether it succeeded or not. Uh, oh!

Fortunately, FindBugs check for this, and helped me find the bug.

Now, wouldn’t it be nice if there were a way to tell FindBugs that users of a certain method you have implemented should never ignore the return value?

And, indeed, there is a way to do that: just annotate the method with @CheckReturnValue, as follows:

@edu.umd.cs.findbugs.annotations.CheckReturnValue( explanation="...")
public String methodWhoseReturnValueShouldNeverBeIgnored( String value ) {
  return value;
}

Now, if you call this method without using the returned value, as follows,

public void useMethodWithCheckReturnValue() {
  // FindBugs warning: you are ignoring the returned value!
  methodWhoseReturnValueShouldNeverBeIgnored ("a value");
}

then FindBugs will complain.

Now, I can think of two main scenarios where you should annotate a method with @CheckReturnValue:

• The method performs an operation for which it is very important to check the result because it indicates success or failure, and your code will probably need to handle these scenarios differently. This is the“forgot to check the result of delete” scenario that caused the bug in DJN.

• You applied an operation to an immutable object, and are returning a new object that is the result of applying the operation to the original unmodified object: it is clear that you must use the returned object from then on, instead of continue using the old unmodified object. For example, most operations on BigDecimal should probably have this annotation.

Using this annotation is so easy that you should probably add it to your programming arsenal.

Tool and library versions

The FindBugs version we have used for this article is 1.3.9, with the corresponding plugin running in Eclipse 3.3.0.

By the way, note that, to use these annotations, you need to add a pair of jars FindBugs provides: annotations.jar and jsr305.jar. However, these jars need not be redistributed, they are used at compile time only.

Related articles

You might be interested in taking a look at other FindBugs posts and articles:

• This article is about using FindBugs annotations to make sure that resources (connections, streams, sockets, etc.) are released.