JAVA.FUNCS.IRV : Ignored Return Value (Java)

Summary

The returned value of a non-void method is thrown away but should instead be checked or used.

The return value is the result of the computation of a method. In some cases, it is expected that this return value gets used rather than dropped, since it contains important information about the outcome of the method or since otherwise the call to the method or constructor would be useless and hence meaningless. The latter situation occurs for calls to pure methods or constructors, that is, code that does not modify the heap memory of the caller. In many cases, this latter situation is the sign of more serious problems in the algorithmic logic of the code.

Tolerating Calls to Methods without Side-Effects

From time to time, it might be useful to instruct the analyzer to tolerate calls to specific methods, although they have no side-effects. For instance, this might be the case of calls to methods that check a condition and throw an exception if the condition does not hold. They are often used as assertions and such calls are not normally wrapped inside a try/catch scope. When this is the case, the programmer can annotate the method with the @TolerateUselessCall annotation, as in the subsequent example:

public static @TolerateUselessCall <T> T notNull(final T object, final String message, final Object... values) {
    if (object == null)
      throw new NullPointerException(String.format(message, values));

    return object;
  }

Without that annotation, a warning would be issued at each call to method notNull().

Properties

WARNING_FILTER += discard class="Ignored Return Value (Java)"

Example

Consider the following program:

import java.io.File;

public class Test {
  private String name;
  private static int counter;

  public Test(String name) {
      this.name = name;
  }

  public Test(String name, int offset) {
      this(name);
      counter += offset;
  }

  public static void main(String[] args) {
      File file = new File("dir");
      file.mkdir();    // Ignored Return Value (Java) warning issued here
      Test t = new Test("John");
      t.getName();     // Ignored Return Value for Pure Function (Java) warning issued here
      new Test("Joan"); // Ignored Return Value for Pure Function (Java) warning issued here
      new Test("Albert", 13);               // ok: has a side effect
  }

  public String getName() {
      return name;
  }
}

In this example, the programmer should for instance modify the program as follows.

import java.io.File;

public class Test {
  private String name;
  private static int counter;

  public Test(String name) {
      this.name = name;
  }

  public Test(String name, int offset) {
      this(name);
      counter += offset;
  }

  public static void main(String[] args) {
      File file = new File("dir");

      if (!file.mkdir()) {
            System.out.println("directory could not be created");
            System.exit(0);
      }
      new Test("Albert", 13);
  }

  public String getName() {
      return name;
  }
}

Resolution

Use the return value of the method or remove the method or constructor call completely, since it has no effect on the heap of the caller, or check if the logic of the code is broken because the return value of a call to a pure method or constructor is not used.

Relevant Configuration File Parameters

The following configuration file parameters affect checks for this warning class.

• REPORT_SIMILAR_WARNINGS
• WARNING_FILTER