Is it bad practice to return an iterable in a method?

Question

I have often read in many places that one should avoid returning an iterable and return a collection instead. For example -

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

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

Note : This question is not about Guava library

Answer 1

Returning an Iterable would be beneficial when we need to lazily load a collection that contains a lot of elements.

The following quote from Google Collections FAQ seems to support the idea of lazy loading:

Why so much emphasis on Iterators and Iterables?

In general, our methods do not require a Collection to be passed in when an Iterable or Iterator would suffice. This distinction is important to us, as sometimes at Google we work with very large quantities of data, which may be too large to fit in memory, but which can be traversed from beginning to end in the course of some computation. Such data structures can be implemented as collections, but most of their methods would have to either throw an exception, return a wrong answer, or perform abysmally. For these situations, Collection is a very poor fit; a square peg in a round hole.

An Iterator represents a one-way scrollable "stream" of elements, and an Iterable is anything which can spawn independent iterators. A Collection is much, much more than this, so we only require it when we need to.

Answer 2

I can see advantages and disadvantages:

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

• One disadvantage is that Iterable is functionality poor. If you have a concrete type that implements Collection, and you return it as an Iterable, you are removing the possibility that the code can (directly) call a variety of useful collection methods.

• There are some cases where neither Iterable or Collection are a good fit; e.g. specialist collections of primitive types ... where you need to avoid the overheads of using the primitive wrapper types.

You can't really say whether it is good or bad practice to return an Iterable. It depends on the circumstances; e.g. the purpose of the API you are designing, and the requirements or constraints that you want / need to place on it.