Skip to content

Commit 0af0184

Browse files
committed
Add detailed null-safety guidelines with JSpecify annotations
1 parent beedf0a commit 0af0184

File tree

1 file changed

+31
-0
lines changed

1 file changed

+31
-0
lines changed

framework-docs/modules/ROOT/pages/core/null-safety.adoc

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,37 @@ public static @Nullable String buildMessage(@Nullable String message,
8080
// ...
8181
}
8282
----
83+
=== Annotation Placement Differences: Traditional vs. JSpecify
84+
85+
It is common for Java developers to place field or method annotations such as
86+
`@NotNull` or `@NotBlank` on a separate line directly above the field or method declaration:
87+
88+
[source,java]
89+
----
90+
@NotBlank
91+
private String lastName;
92+
----
93+
94+
In contrast, JSpecify annotations like `@Nullable` are type-use annotations,
95+
which means they apply to the type itself rather than the field or method declaration.
96+
This subtle distinction is important because it allows for more precise
97+
nullability declarations, including complex cases like arrays and generics.
98+
99+
Therefore, the recommended style for JSpecify annotations is to place them
100+
on the same line as the type, immediately preceding the type name:
101+
102+
[source,java]
103+
----
104+
private @Nullable String lastName;
105+
private @Nullable String @Nullable [] names;
106+
----
107+
108+
This approach enhances clarity by showing the nullability of the type directly,
109+
and it aligns with the Java Language Specification rules for type-use annotations.
110+
111+
Note that mixing traditional annotations on a separate line and JSpecify
112+
annotations on the same line can look inconsistent, but it reflects the
113+
different semantics and targets of these annotations.
83114

84115
[NOTE]
85116
====

0 commit comments

Comments
 (0)