Is bad practice returning iterability in a method?

Question

I often read in many places that you should avoid returning iterable and instead returning collection . For instance -

 public Iterable<Maze> Portals() { // a list of some maze configurations List<Maze> mazes = createMazes(); ... return Collections.unmodifiableList(mazes); } 

Since returning iterable is only useful for use in the foreach , and collection already provides an iterator and provides much more control. Could you tell me when it is useful to specifically return the iterable method in a method? Or should we always return collection ?

Note. This question is not about the Guava library.

Answer 1

Returning Iterable would be useful when we needed to lazily load a collection containing many elements.

The following quote from the Google Collections FAQ supports the idea of ​​lazy loading:

Why is so much attention paid to iterators and iterators?

In general, our methods do not require the collection to be passed in when an Iterator or Iterator is enough. This difference is important for us, because sometimes we work with Google with very large amounts of data, which may be too large to fit in memory, but which can be passed from beginning to end during some calculation. Such data structures can be implemented as collections, but most of their methods would either throw an exception, return an incorrect answer, or commit horribly. For these situations, the collection is very poor; square pin in a round hole.

An iterator is a unidirectional scrollable "stream" of elements and Iterable is all that independent iterators can generate. A collection is much, much larger than that, so we demand it only when we need it.

Answer 2

The problem is that if the basic changes to the collection you have problems. If you use a collection that throws a concurrentmodification exception, then you should also take care of this, but there are no such problems with the collection.

Answer 3

Return the most specific type that makes sense for use. For example, if you have a method of creating a new collection, or you can easily wrap a collection in an unmodifiable shell, returning the collection as Collection or even List or Set , makes the client developer life a little easier.

The Iterable return makes sense for code in which values ​​can be generated on the fly; you could imagine, for example, the Fibonacci generator that created Iterator , which calculated the next number instead of trying to save some lookup table. If you are writing a framework or interface code where such a “streaming” kind of API can be useful (Guava and its functional classes do this a little), then specifying Iterable instead of the type of the collection may be worth the loss of flexibility on the consumer side.

Answer 4

I see the advantages and disadvantages:

• One of the advantages is that Iterable is a simpler interface than Collection . If you have a custom collection type, it may be easier to make it Iterable than Collection . Indeed, there are some types of collections for which some of the Collection methods are problematic to implement. For example, lazy collection types and collections where you do not want to rely on the standard equals(Object) method to determine membership.

• One of the drawbacks is that Iterable not functioning well. If you have a specific type that implements Collection , and you return it as Iterable , you remove the possibility that the code can (directly) call many useful collection methods.

• There are times when neither Iterable nor Collection is suitable; for example, specialized collections of primitive types ... where you need to avoid the overhead of using primitive wrapper types.

You cannot say whether it is good or bad practice to return Iterable . It depends on the circumstances; for example, the purpose of the API being designed, as well as the requirements or restrictions that you want / need to place on it.