Merge "go/android-api-guidelines#methods-prefer-collection-over-array - clarify that arrays should also be @NonNull" into main
diff --git a/api-guidelines/methods.md b/api-guidelines/methods.md
index b6acb40..7d62f52 100644
--- a/api-guidelines/methods.md
+++ b/api-guidelines/methods.md
@@ -1128,6 +1128,21 @@
Where type annotations are supported, always prefer `@NonNull` for collection
elements.
+You should also prefer `@NonNull` when using arrays instead of collections
+(see [previous item](#methods-prefer-collection-over-array)). If object
+allocation is a concern, create a constant and pass it along - after
+all, an empty array is immutable. Example:
+
+``` java {.good}
+private static final int[] EMPTY_USER_IDS = new int[0];
+
+@NonNull
+public int[] getUserIds() {
+ int [] userIds = mService.getUserIds();
+ return userIds != null ? userIds : EMPTY_USER_IDS;
+}
+```
+
### Collection mutability <a name="methods-collections-mutability"></a>
Kotlin APIs should prefer read-only (e.g. not `Mutable`) return types for
