Immutability and general in relation to specific types

Question

This is in the context of creating an interface / API.

Best practices suggest using generic rather than specific types in interfaces — for example Map, rather than HashMap.

Best practices also suggest the preference for immutable types over mutable ones.

Thus, given both of these suggestions (and leaving aside problems with performance / footprint memory, third-party libraries / dependencies, and usability / functionality), the method should look like in the public interface

public List<SomeClass> someMethod(...)

or rather it is

public ImmutableList<SomeClass> someMethod(...)

Answer 1

When this was discussed among the people of Guava, the following was said:

, API, : , - .

, , ImmutableCollection, ( , ). ImmutableSet, Set.

, ImmutableSet .. . : , Java JDK 8, .

, ImmutableList , ; .

Answer 2

, , ImmutableList, List. , , List JavaDoc.

, , , .

Answer 3

API- - .

, API- .

. , , , .

If the API will be consumed internally (with the same code base), and the goal is to achieve loose communication, you need to think about ease of writing, extensibility and maintainability.

Immutable APIs will avoid data inconsistency, especially if you have made a lot of assumptions about the state of the object. A volatile facility, on the other hand, will help maintain development efforts.