File tree Expand file tree Collapse file tree 1 file changed +31
-0
lines changed
framework-docs/modules/ROOT/pages/core Expand file tree Collapse file tree 1 file changed +31
-0
lines changed Original file line number Diff line number Diff line change @@ -80,6 +80,37 @@ public static @Nullable String buildMessage(@Nullable String message,
80
80
// ...
81
81
}
82
82
----
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.
83
114
84
115
[NOTE]
85
116
====
You can’t perform that action at this time.
0 commit comments