Use Custom Generic Collections Rather Than Generic Lists in Public API

God breathing through me

Use Custom Generic Collections Rather Than Generic Lists in Public API

Published on February 13, 2008

During my development experience with generic lists in .NET 2.0 and later and working with different collection types in .NET I found that using generic lists as parameter or return types in public API wouldn't be the best idea (it's not a bad idea but not the best one, though!).

This is especially important for me when I work on a professional library or a framework where more considerations matter for me and end users of the work.

I have some reasons behind my thoughts to use an alternative method (that I'll describe in a moment). When you use a generic list as your parameter and return type, readability and extensibility of your code can't be the best.

My approach (which isn't just mine and some other developers are using it) is rather than using a generic list I'd prefer to use a class that derives from the generic list with a constant naming pattern in a project.

For instance, look at the following code that represents a blog post in its simplest form.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
namespace GenericListsSample
{
    public class BlogPost
    {
        public int ID { get; set; }
 
        public string Title { get; set; }
 
        public string Body { get; set; }
 
        public DateTime PublishDate { get; set; }
 
        public string Name { get; set; }
 
        public string AuthorName { get; set; }
    }
}

Now consider that I want to get a list of recent blog posts in my API. I have several options like using an ArrayList or some other traditional collection types, using a generic list of BlogPost objects and a third option that is based on the second option and I pointed above.

Obviously you no more want to use the traditional approaches so will end up with one of the generic list approaches. But I'd prefer to do an extra step and create a class like BlogPostCollection as you see here:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
namespace GenericListsSample
{
    public class BlogPostCollection : List<BlogPost>
    {
    }
}

You may wonder why I didn't simply use a generic list of BlogPost? I found two positive points for this.

First is about the extensibility power that it gives to me. So if one day I decide to add something new to my list then I can simply add my code to BlogPostCollection and this is very easy. This is especially helpful when I work on a framework or library that is large and this makes the future development much easier. Moreover, I can keep my design constant and it prevents future changes of the public API.

The second positive point about this approach is improving the readability of code and simplicity of the framework design. If I follow the same naming convention in my design (i.e. adding a "Collection" postfix to the name of a class) then end users can work with the code easily and find things quicker.

The following class implementation shows the usage of both approaches to get a list of recent blog posts.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
namespace GenericListsSample
{
    public static class BlogManager
    {
        public static List<BlogPost> GetPostsWithGenericList(int postCount)
        {
            // Implement the logic
            throw new NotImplementedException();
        }
 
        public static BlogPostCollection GetPostsWithCustomGenericList(int postCount)
        {
            // Implement the logic
            throw new NotImplementedException();
        }
    }
}

I found this approach a better way to keep consistency in my framework design and a good way to extend my code in the future. I can't remember where I had seen for the first time but I just inspired this from other's code. I also saw that this is used in Graffiti API as well.

5 Comments

Brendan Enrick
Feb 11, 2008 10:21 AM
#

That is a nice idea. I like that it requires pretty much no extra effort and also it allows you to make extra changes to the library without changing the API.

Patrik Hägne
Feb 11, 2008 5:25 PM
#

You take up some very good points here and it's something that I'd hope for most developers to learn. I was inspired by your post and expanded a little on the subject on my blog, please read it at: ondevelopment.blogspot.com/.../exposing-collec

nyi nyi thann
Feb 11, 2008 11:51 PM
#

Hi,

Thanks. I am clear now. I am usually indecisive which way to chose-Generic List or Custom Generic list.

Please post about .net collection if possible.

.Net Adventures
Feb 12, 2008 1:39 PM
#

I think returning an interface(IBlogPostCollection) is a better solution.The solution prevents users of the interface from using class protected members or methods.

Keyvan Nayyeri
Feb 12, 2008 1:42 PM
#

@.Net Adventures:

No, I don't think. One of the main reasons to use this approach is the ability for future extensibility while interfaces don't allow this very well.

Keyvan Nayyeri

Recent Posts

Archive

Use Custom Generic Collections Rather Than Generic Lists in Public API

Leave a Comment