== Why is this an issue?

Callers of a `Boolean` method may be expecting to receive `true` or `false` in response.
But `Boolean` objects can take `null` as a possible value.
`Boolean` methods should not return `null` unless the code is annotated appropriately.
With the proper annotation, the caller is aware that the returned value could be null.

=== Noncompliant code example

[source,java]
----
public Boolean isUsable() {
  // ...
  return null;  // Noncompliant
}

public void caller() {
  if (isUsable()) { // A NullPointerException might occur here
    // ...
  }
}
----

=== Compliant solution

[source,java]
----

@javax.annotation.Nullable
public Boolean isUsable() {
  // ...
  return null;
}

@javax.annotation.CheckForNull
public Boolean isUsable() {
  // ...
  return null;
}

public void caller() {
  if (Boolean.True.equals(isUsable())) { // This caller knows to check and avoid ambiguity
    // ...
  }
}
----


== Resources

* CWE - https://cwe.mitre.org/data/definitions/476[CWE-476 - NULL Pointer Dereference]
* https://wiki.sei.cmu.edu/confluence/x/aDdGBQ[CERT, EXP01-J.] - Do not use a null in a case where an object is required

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Null is returned but a "Boolean" is expected.


endif::env-github,rspecator-view[]