Type annotations

Nullness annotations

We are using the Eclipse JDT nullness annotations.

As long as we do not fully agree about the usage of that annotations its usage is described here and not in the coding guidelines.

Add the following line org.eclipse.jdt.annotation;resolution:=optional to your Import-Package section of your OSGi manifest.

Comments like "ensure correct usage" should be seen as "if the Eclipse IDE nullness checking has been enabled".

If a function argument or parameter is not annotated, it could be null.
Use @NonNull annotation for function arguments that must not be null to ensure correct usage.
Use @Nullable for return values if they could be null, to ensure the caller handles the return value correctly.
Don't use @Nullable on function parameters.
- That is the point we do not agree at the moment.
Use @NonNull for return types to state that null must not be returned and the consumer could rely on it.
- This is something we currently think about.

Comments like "ensure correct usage" should be seen as "if the Eclipse IDE nullness checking has been enabled".

The final result of our null annotation usage should be that classes are annotated by @NonNullByDefault and return types, parameter types etc. are annotated with @Nullable only. There is no need for a @NonNull annotation because it is set as default.
As long as we are in a transition phase it could be hard work to annotate the whole class. As long as the whole class cannot be annotated to use a default annotation we are allowed to use @Nullable and @NonNull annotations for return types, parameter types etc. As soon as it is possible to set the default annotation for the class all redundant usages of @NonNull should be removed.
@NonNull and @Nullable will be (not only in the transition phase but all the time) allowed for generic type arguments. So we could mark that e.g. a map must contain only non-null values of a collection does not contain a nullable entry etc.
We are using the Eclipse External Annotation support to add annotations for the JRE and third party libraries.

Classes should be annotated by @NonNullByDefault and return types, parameter types, generic types etc. are annotated with @Nullable only. There is no need for a @NonNull annotation because it is set as default.
We are using the Eclipse External Annotation support to add annotations for the JRE and third party libraries.
The transition of existing classes could be a longer process but if you want to use nullness annotation in a class / interface you need to set the default for the whole class and annotate all types that differ from the default.