Empty immutable collections should be explicitly documented as singletons

ImmutableList.of() says this:

Returns the empty immutable list. This set behaves and performs comparably to Collections.emptyList(), and is preferable mainly for consistency and maintainability of your code.

The use of the phrase “the empty immutable list” suggests that this method always returns the same object, as indeed it does. But this is implied only by the use of the definite article and the reference to Collections.emptyList(). It would be better to state it more explicitly. By comparison, Collections.emptyList() itself says this:

Implementation note: Implementations of this method need not create a separate List object for each call. Using this method is likely to have comparable cost to using the like-named field. (Unlike this method, the field does not provide type safety.)

Of course the same applies to the other empty-collection methods.

[ronshapiro]

We treat ImmutableList as an interface in that sense. It has meaningful semantics that are frequently relevant for a caller to know. In the same way that you can return a Collection vs. a Set, even though Set doesn’t have any different methods, it is clearly a different type.

On Fri, May 11, 2018, 8:41 AM Ivo Šmíd [e-mail] wrote:

I understand what you mean, but it works only when you have ImmutableList at signatures, but when you prefer coding against interface, you have List there…

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/google/guava/issues/2083#issuecomment-388352087, or mute the thread https://github.com/notifications/unsubscribe-auth/AAwY3dJfS_cvFa3ZOiXnEpUJssqgDsM0ks5txYbpgaJpZM4FFxpc .

[cpovirk]

(Oh, and I was also going to note that we could conceivably make similar changes for Optional.absent and quite possibly other types.)