I guess, with your annotation you want to do two things:
- make the program faster
- make the programmers have to work less (because they don't have to type the null-checks)
For the first one: A Null-check consumes hardly any resources. If you run this sample:
public static void main(String[] args) {
long ms = System.currentTimeMillis();
for (int i=0;i<10000;i++) {
returnsNonNull(i);
doNothing();
}
System.out.println("Without nullcheck took "+(System.currentTimeMillis()-ms)+" ms to complete");
ms = System.currentTimeMillis();
for (int i=10000;i<20000;i++) {
if (returnsNonNull(i)!=null) {
doNothing();
}
}
System.out.println("With nullcheck took "+(System.currentTimeMillis()-ms)+" ms to complete");
}
public static String returnsNonNull(int i) {
return "Foo "+i+" Bar";
}
public static void doNothing() {
}
You will see, there is hardly any difference between these two tests. The second one (with the null-check) is sometimes even faster than the first one, meaning they both are pretty much indistinguishable when it comes to resource use.
Now to the second point:
You are actually making the programmers work more, not less. Except if there are absolutely no functions in your whole project and framework that ever return null the programmer now has to look up the function each time to check if he has to do a null-check or not. Seeing that about every framework in Java can under some conditions return null in some functions you are not reducing the workload for your programmers.
You said you want a warning to appear when they do a null-check where it is not necessary because of your @Nonnull-annotation. So what they will do is they type out the whole null-check and then get a warning and have to remove it again. See what I mean?
Also what if you make a mistake in your code and mark something as @Nonnull that can return null?
What I'd do is write it into the Javadoc under @return. Then the programmer can decide what he does, which is usually better than forcing others to write code your style.