Add detailed null-safety guidelines with JSpecify annotations

Signed-off-by: Ananya Kulkarni <tok2ananya@gmail.com>
This commit is contained in:
Ananya Kulkarni 2025-06-27 18:06:20 -05:00
parent beedf0a76b
commit 38e28b3b42
1 changed files with 31 additions and 0 deletions

View File

@ -80,6 +80,37 @@ public static @Nullable String buildMessage(@Nullable String message,
// ... // ...
} }
---- ----
=== Annotation Placement Differences: Traditional vs. JSpecify
It is common for Java developers to place field or method annotations such as
`@NotNull` or `@NotBlank` on a separate line directly above the field or method declaration:
[source,java]
----
@NotBlank
private String lastName;
----
In contrast, JSpecify annotations like `@Nullable` are type-use annotations,
which means they apply to the type itself rather than the field or method declaration.
This subtle distinction is important because it allows for more precise
nullability declarations, including complex cases like arrays and generics.
Therefore, the recommended style for JSpecify annotations is to place them
on the same line as the type, immediately preceding the type name:
[source,java]
----
private @Nullable String lastName;
private @Nullable String @Nullable [] names;
----
This approach enhances clarity by showing the nullability of the type directly,
and it aligns with the Java Language Specification rules for type-use annotations.
Note that mixing traditional annotations on a separate line and JSpecify
annotations on the same line can look inconsistent, but it reflects the
different semantics and targets of these annotations.
[NOTE] [NOTE]
==== ====