Merge "Add section about mutability of returned data-type objects" into main

api-guidelines/methods.md

diff --git a/api-guidelines/methods.md b/api-guidelines/methods.md
index ce2cd02..1554235 100644
--- a/api-guidelines/methods.md
+++ b/api-guidelines/methods.md
@@ -1171,8 +1171,8 @@
 implementation of immutable collections. The exception to this rule is
 `Collections.empty` return types, which are immutable. In cases where mutability
 could be exploited by clients -- on purpose or by mistake -- to break the API's
-intended usage pattern, Java APIs should return a shallow copy of the
-collection.
+intended usage pattern, Java APIs should strongly consider returning a shallow
+copy of the collection.
 
 ```java {.bad .no-copy}
 @Nullable
@@ -1195,10 +1195,9 @@
 
 APIs that return collections should ideally not modify the returned collection
 object after returning. If the returned collection must change or be reused in
-some way, for example, an adapted view of a mutable data set, the precise
-behavior of when the contents of a previously returned collection can change
-must be documented and/or appeal to an appropriate established convention. For
-example:
+some way -- for example, an adapted view of a mutable data set -- the precise
+behavior of _when_ the contents can change must be explicitly documented and/or
+follow established API naming conventions.
 
 ```kotlin {.good .no-copy}
 /**
@@ -1211,6 +1210,31 @@
 [below](#kotlin-conversion-functions) and permits the collection returned by
 `.asList()` to change if the original collection changes.
 
+### Mutability of returned data-type objects <a name="methods-mutability-return"></a>
+
+Similar to APIs that return collections, APIs that return data-type objects
+should ideally not modify the properties of the returned object after returning.
+
+```kotlin {.bad}
+val tempResult = DataContainer()
+
+fun add(other: DataContainer): DataContainer {
+  tempResult.innerValue = innerValue + other.innerValue
+  return tempResult
+}
+```
+
+```kotlin {.good}
+fun add(other: DataContainer): DataContainer {
+  return DataContainer(innerValue + other.innerValue)
+}
+```
+
+In _extremely_ limited cases, some performance-sensitive code may benefit from
+object pooling or reuse. *Do not* write your own object pool data structure and
+*do not* expose reused objects in public APIs. In either case, be extremely
+careful about managing concurrent access.
+
 ### Use of `vararg` parameter type <a name="methods-vararg"></a>
 
 Both Kotlin and Java APIs are encouraged to use `vararg` in cases where the