Annotations for Nullable and NonNull return values / parameters / fields

For some time, we have a @Null (source) annotation in libGDX. This triggered a discussion on the Discord server recently, because some of us think that the existing annotation could be improved. Our pain points here are the following:

• There is no NonNull annotation guaranteeing non-null values
• The Null annotation doesn’t match the general convention that it is named “Nullable”

Moreover, we think that there are some more benefits that could be achieved by such an annotation. Nullable and NonNull annotations can be used by the major IDEs and by Kotlin to determine nullability. The Kotlin compiler even infers the types needed for params and return values in Java interoperability from these annotations, which - in case of NonNull makes it possible to reduce a lot of Null-Checks.

As far as we could find out, our annotations have to match the following to be compatible to the following products:

• Eclipse: Nullable/NonNull annotations are fully configurable
• Kotlin: the annotations have to be in certain packages to be used. The compiler source tells us which can be used. It depends on certain package names: androidx.annotation.Nullable, javax.annotation.Nullable, edu.umd.cs.findbugs.annotations.Nullable, io.reactivex.annotations.Nullable and more
• IntelliJ/Android Studio: Not 100% sure, but it seems that it accepts the same annotations as Kotlin does

So far so good. If we decide to match the world outside libGDX, there are some more points to decide:

• Which annotation (package) should be used?
• Should we add a dependency, or should we add the annotations ourselves?

@obigu found a great StackOverflow post on the first topic, listing from which standpoints the decision can be made and how the candidates perform.

Personally, I think we should not adopt annotations retained at runtime - most games won’t need this. It looks like the jsr305spotbugs annotations are still the best to use, but we might missed some needs so this is intended to start a discussion.

[PokeMMO]

Should we add a dependency, or should we add the annotations ourselves?

Imo, we should not be shipping a class in any of those packages. If we want to match those packages, we need to add them as a dependency.

[obigu]

Naming

I prefer @Null because it is short. It’s pretty obvious that it doesn’t mean the value is always null. I don’t think naming it @Nullable is any more descriptive, nor do I find it important that most other projects prefer @Nullable. Since there is no standard, tools should be configurable.

I think it’s worth listing the pros and cons of each option.

Pros of @Null

• 4 characters long

Cons of @Null

• Breaks convention
• Shares name with javax.validation.constraints.Null annotation (which actually checks for null value)
• Semmantically wrong

Pros of @Nullable

• It’s the naming by widely adopted convention (even if it’s not a standard as JSR-305 has not been adopted)
• Self-documenting code

Cons of @Nullable

• 8 characters long

IMO the fact that it’s shorter is much less important compared to the other points.