Why would I use Lombok-Annotation @NonNull?

Question

Lombok offers the annotation @NonNull which executes the nullcheck and throws a NPE (if not configured differently).

I do not understand why I would use that annotation as described in the example of that documentation:

private String name;
public NonNullExample(@NonNull Person person) {
    super("Hello");
    if (person == null) {
      throw new NullPointerException("person is marked @NonNull but is null");
    }
    this.name = person.getName();
  }

The NPE would be thrown anyway. The only reason here to use the annotation imo is if you would want the exception to be different from a NPE.

EDIT: I do know that the Exception would be thrown explicitly and thus 'controlled', but at least the text of the error message should be editable, shouldn't it?

Answer 1

Writing a type annotation such as @NonNull serves several purposes.

• It is documentation: it communicates the method's contract to clients, in a more concise and precise way than Javadoc text.
• It enables run-time checking -- that is, it guarantees that your program crashes with a useful error message (rather than doing something worse) if a buggy client mis-uses your method. Lombok does this for you, without forcing the programmer to write the run-time check. The referenced example shows the two ways to do this: with a single @NonNull annotation or with an explicit programmer-written check. The "Vanilla Java" version either has a typo (a stray @NonNull) or shows the code after Lombok processes it.
• It enables compile-time checking. A tool such as the Checker Framework gives a guarantee that the code will not crash at run time. Tools such as NullAway, Error Prone, and FindBugs are heuristic bug-finders that will warn you about some mis-uses of null but do not give you a guarantee.

Answer 2

IMHO, you've understood that documentation page wrongly.

That documentation page doesn't imply that you are recommended to use both Lombok @NonNull annotations and explicit if (smth == null) throw …-like checks as the same time (in the same method).

It just says that a code like this one (let's call it code A):

import lombok.NonNull;

public class NonNullExample extends Something {
  private String name;

  public NonNullExample(@NonNull Person person) {
    super("Hello");
    this.name = person.getName();
  }
}

will be automatically (internally) translated by Lombok into a code like the one quoted the question (let's call it code B).

But that documentation page doesn't say that it would make sense for you to explicitly write the code B (though you are allowed; and Lombok will even try to prevent double check in this case). It just says that with Lombok you are now able to write the code A (and how it will work — it will be implicitly converted into the code B).

Note, that the code B is a “vanilla Java” code. It isn't expected to be processed by the Lombok for the second time. So @NonNull in the code B is just a plain annotation, which has no influence on the behavior (at least, not by Lombok means).

It's a separate question why Lombok works in that way — why it doesn't remove @NonNull from the generated code. Initially I even thought that it might be a bug in that documentation page. But, as Lombok author explains in his comment, @NonNulls are intentionally kept for the purposes of documentation and possible processing by other tools.