The short answer to your question: this is how it is designed…
And just as a side note, we (Sonarsource) are not designing these annotations, we are using them to detect issues.
The long answer is that we need something between “never returns null” (no annotation) and “always check if return null” (@CheckNotNull). It is useful, among other things, for other rules to works correctly.
For example, let’s take this scenario:
I want to write a method: public List<String> f(String s).
I want this method to return null if the argument is null.
public List<String> f(String s) {
if (s == null) {
return null;
}
// More logic
}
However, our dear analyzer will trigger RSPEC-1168. For some curious reason, I really want to return null here. So I annotate the method with @CheckNotNull. The issue disappears because the annotation shows that this is not a careless mistake, I make explicit that this method can return null and the user will be aware of that.
Now, the problem is when I’m using my method:
f("abc").length(); // Issue java:S2259, a NPE is possible! Really?
I will always have to check the return value for nullness despite the fact that I’m sure it can not be null because the only cases where it will return null are explicit.
At this point, I want something that would show that I and users are perfectly aware that my method can return null, to comply with S1168, and to not impose a cumbersome check for null when it is obviously not. The solution is nothing else than @Nullable.