jakartaee / jakartaee/common-annotations-api

Nullness annotations do not reflect the state of the art

Open
#110 5 comments 6 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
67
Forks
42
PR merge metrics
No merged PRs in 30d

Description

Annotations `@Nonnull` and `@Nullable` are not specified with the level of detail that would be needed to make this a worthwhile new standard. Since more advanced approaches exist for many years, I suggest to coordinate with those parties having worked in this area.

Some issues with the existing annotations:
* All experts that I talked to agree that nowadays only `TYPE_USE` annotations should be used for this purpose, as only those support a degree of annotating the code that will allow analysis tools to give qualified answers.
* Even worse, an annotation without any `@Target` meta annotation will for some corner cases (relating to arrays) affect two locations simultaneously, which makes for a completely obscure pitfall.
* It is commonly agreed, that at least one more annotation is needed for practical use: some defaulting annotation, like `@NonNullByDefault`

The most pressing issue in this area is the abundance of too many similar annotations. Adding one more set in jakarta only aggravates the problem.

Prior art that should be taken into consideration includes:
* https://checkerframework.org/manual/#nullness-checker by the authors of JSR-308
* Eclipse JDT, talk to me for details. Our approach has been closely coordinated with the Checker Framework people.
* https://jspecify.dev/ -- more recent attempt to standardize
* JetBrains has also worked in this area, but I cannot provide a reference to a contact.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing @Nonnull and @Nullable annotations and the Checker Framework, Eclipse JDT, and JSpecify prior art linked in the issue. Compare their use of TYPE_USE, @Target, and defaulting annotations such as @NonNullByDefault, then coordinate with the referenced experts. Done requires an agreed direction for a Jakarta nullness annotation standard.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.