IEnumerable<T> as return type

Question

Is there a problem with using IEnumerable<T> as a return type? FxCop complains about returning List<T> (it advises returning Collection<T> instead).

Well, I've always been guided by a rule "accept the least you can, but return the maximum."

From this point of view, returning IEnumerable<T> is a bad thing, but what should I do when I want to use "lazy retrieval"? Also, the yield keyword is such a goodie.

Cerallua

Answer 1

This is really a two part question.

1) Is there inherently anything wrong with returning an IEnumerable<T>

No nothing at all. In fact if you are using C# iterators this is the expected behavior. Converting it to a List<T> or another collection class pre-emptively is not a good idea. Doing so is making an assumption on the usage pattern by your caller. I find it's not a good idea to assume anything about the caller. They may have good reasons why they want an IEnumerable<T>. Perhaps they want to convert it to a completely different collection hierarchy (in which case a conversion to List is wasted).

2) Are there any circumstances where it may be preferable to return something other than IEnumerable<T>?

Yes. While it's not a great idea to assume much about your callers, it's perfectly okay to make decisions based on your own behavior. Imagine a scenario where you had a multi-threaded object which was queueing up requests into an object that was constantly being updated. In this case returning a raw IEnumerable<T> is irresponsible. As soon as the collection is modified the enumerable is invalidated and will cause an execption to occur. Instead you could take a snapshot of the structure and return that value. Say in a List<T> form. In this case I would just return the object as the direct structure (or interface).

This is certainly the rarer case though.

Malm

As the OP indicates, if a concrete class needs to be returned, FxCop advises returning a Collection<T> rather than a List<T>. Also see Collection<T> versus List<T> what should you use on your interfaces?. – Mossy

Answer 2

No, IEnumerable<T> is a good thing to return here, since all you are promising is "a sequence of (typed) values". Ideal for LINQ etc, and perfectly usable.

The caller can easily put this data into a list (or whatever) - especially with LINQ (ToList, ToArray, etc).

This approach allows you to lazily spool back values, rather than having to buffer all the data. Definitely a goodie. I wrote-up another useful IEnumerable<T> trick the other day, too.

Liebig

any thoughts on why fxcop complains? – Nutter

Does it complain about returning IEnumerable<T>? If so, take it with a pinch of salt... it isn't always right. – Liebig

If it prompts you to think about what you really want to return, fxcop has done its job ;-p – Liebig

I'm pretty sure it only complains about List<T>, not IEnumerable<T>. Unless I have it excluded somewhere, it doesn't complain on my code that returns IEnumerable<T> – Rovner

Answer 3

IEnumerable is fine by me but it has some drawbacks. The client has to enumerate to get the results. It has no way to check for Count etc. List is bad because you expose too much control; the client can add/remove etc. from it and that can be a bad thing. Collection seems the best compromise, at least in FxCop's view. I always use what seems appropiate in my context (eg. if I want to return a read only collection I expose collection as return type and return List.AsReadOnly() or IEnumerable for lazy evaluation through yield etc.). Take it on a case by case basis

Gagman

The client can use ToList(), ToArray(), Count() or whatever it wants. – Fug

but those methods create new objects. any modifications done do not reflect on the original list object – Gagman

Good point! case-by-case basis seems best. Although I prefer the IEnumerable approach, it favors immutability. – Fug

Answer 4

Returning IEnumerable<T> is OK if you're genuinely only returning an enumeration, and it will be consumed by your caller as such.

But as others point out, it has the drawback that the caller may need to enumerate if he needs any other info (for example Count). The .NET 3.5 extension method IEnumerable<T>.Count will enumerate behind the scenes if the return value does not implement ICollection<T>, which may be undesirable.

I often return IList<T> or ICollection<T> when the result is a collection - internally your method can use a List<T> and either return it as-is, or return List<T>.AsReadOnly if you want to protect against modification (e.g. if you're caching the list internally). AFAIK FxCop is quite happy with either of these.

Clarify

Answer 5

About your principle: "accept the least you can, but return the maximum".

The key to managing the complexity of a large program is a technique called information hiding. If your method works by building a List<T>, it's not often necessary to reveal this fact by returning that type. If you do, then your callers may modify the list they get back. This removes your ability to do caching, or lazy iteration with yield return.

So a better principle is for a function to follow is: "reveal as little as possible about how you work".

Jaramillo

Answer 6

"accept the least you can, but return the maximum" is what I advocate. When a method returns an object, what justifications we have to not return the actual type and limit the capabilities of the object by returning a base type. This however raises a question how do we know what the "maximum" (actual type) will be when we design an interface. The answer is very simple. Only in extreme cases where the interface designer is designing an open interface, which will be implemented outside the application/component, they would not know what the actual return type may be. A smart designer should always consider what the method should be doing and what an optimal/generic return type should be.

E.g. If I am designing an interface to retrieve a vector of objects, and I know the count of returned objects are going to be variable, I'll always assume a smart developer will always use a List. If someone plans to return an Array, I'd question his capabilities, unless he/she is just returning the data from another layer that he/she doesn't own. And this is probably why FxCop advocates for ICollection (common base for List and Array).

The above being said, there are couple of other things to consider

• if the returned data should be mutable or immutable

• if the returned data be shared across multiple callers

Regarding the LINQ lazy evaluations I am sure 95%+ C# users don't understand the intestacies. It’s so non-oo-ish. OO promotes concrete state changes on method invocations. LINQ lazy evaluation promotes runtime state changes on expression evaluation pattern (not something non-advanced users always follow).

Ligule

Answer 7

One important aspect is that when you return a List<T> you are actual returning a reference. That makes it possible for a caller to manipulate your list. This is a common problem—for instance, a Business layer that returns a List<T> to a GUI layer.

Aspidistra

But don't you return a reference any time you're returning something that isn't a value type? – Kwasi

Answer 8

IEnumerable is cool because you can use the yield iterator that gives to the consumer just the data they need but there is a cost hidden in the construct.

Let me explain it with an example. Let's say I am consuming this method:

IEnumerable GetFilesFromFolder(string path)

So, what do I get? To get all the files of my folder I have to iterate the enumeration, and that's fine, after all that's how enumerations work, but what if, for any reason, I have to enumerate it twice?

The second time should I expect a refreshed result or the result is idempotent? I do not know. I have to check the docs of the library / method.

The call to the GetEnumerator method of the enumeration done by the consumer, could, in fact, execute an I/O operation behind the scene, or an http call, or it could simply iterate an inner array, I can not know it for sure. I have to check the docs in the hope that this behavior is documented.

Does this detail matters? I think it does. At least from a performance perspective.

Even if the cost of iterations is slow and CPU bounded, this is not zero, and it could go even worse in the scenario of chains of enumerations, that often turn debugging sessions a nightmare.

I prefer to not give the consumer of my library doubts so whenever I know my API returns few elements I always use arrays as return type, and only when the data to return is huge I use IEnumerable or IAsyncEnumerable.

Anyway, if you want to return enumerations please document your API to tell consumers if the result is a snapshot or not.

Obsolete

Answer 9

Just because you say you're returning IEnumerable doesn't mean you can't return a List. The idea is to reduce unneeded coupling. All that the caller should care about is getting a list of things, rather than the exact type of collection used to contain that list. If you have something that's backed by an array, then getting something like Count is going to be fast anyway.

Escobedo

If the caller expects a list, then IList[<T>] would be a good option. – Liebig

Answer 10

I think your own guidance is great -- if you are able to be more specific about what you're returning without a performance hit (you don't have to e.g. build a List out of your result), do so. But if your function legitimately doesn't know what type it's going to find, like if in some situations you'll be working with a List and in some with an Array, etc., then returning IEnumerable is the "best" you can do. Think of it as the "greatest common multiple" of everything you might want to return.

Kassel

Answer 11

I can't accept the chosen answer. There are ways of dealing with the scenario described but using a List or whatever else your using isn't one of them. The moment the IEnumerable is returned you have to assume that the caller might do a foreach. In that case it doesn't matter if the concrete type is List or spaghetti. In fact just indexing is a problem especially if items are removed.

Any returned value is a snapshot. It may be the current contents of the IEnumerable in which case if it's cached it should be a clone of the cached copy; if it's supposed to be more dynamic (like the resuts of a sql query) then use yield return; however allowing the container to mutate at will and supplying methods like Count and indexer is a recipe for disaster in a multithreaded world. I haven't even gotten into the ability of the caller to call Add or Delete on a container your code is supposed to be in control of.

Also returning a concrete type locks you into an implementation. Today internally you may be using a list. Tomorrow maybe you do become multithreaded and want to use a thread safe container or an array or a queue or the Values collection of a dictionary or the output of a Linq query. If you lock yourself into a concrete return type then you have to either change a bunch of code or do a conversions before returning.

Diopside