Let's say I'm writing a method that should return a Map. For instance:
public Map<String, Integer> foo() {
return new HashMap<String, Integer>();
}
After thinking about it for a while, I've decided that there is no reason to modify this Map once it is created. Thus, I would like to return an ImmutableMap.
public Map<String, Integer> foo() {
return ImmutableMap.of();
}
Should I leave the return type as a generic Map, or should I specify that I'm returning an ImmutableMap ?
From one side, this is exactly why interfaces were created for; to hide the implementation details.
On the other hand, if I'll leave it like this, other developers might miss the fact that this object is immutable. Thus, I won't achieve a major goal of immutable objects; to make the code more clear by minimizing the number of objects that can change. Even worst, after a while, someone might try to change this object, and this will result in a runtime error (The compiler will not warn about it).
If you are writing a public-facing API and that immutability is an important aspect of your design, I would definitely make it explicit either by having the name of the method clearly denotes that the returned map will be immutable or by returning the concrete type of the map. Mentioning it in the javadoc is not enough in my opinion.
Since you're apparently using the Guava implementation, I looked at the doc and it's an abstract class so it does give you a bit of flexibility on the actual, concrete type.
If you are writing an internal tool/library, it becomes much more acceptable to just return a plain
Map. People will know about the internals of the code they are calling or at least will have easy access to it.
My conclusion would be that explicit is good, don't leave things to chance.