Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

Thomas Tomiczek — Mon, 15 Mar 2004 21:43:00 GMT

Gratulations.

What a long post on something that is totally irrelevant for everyone (besides very frew EAP
's) for another year.

May I suggest you push for a faster release :-)

New Blogger on Framework Design Guidelines

Brad Abrams — Mon, 15 Mar 2004 22:03:00 GMT

New Design Guideline: Generics

Brad Abrams — Mon, 15 Mar 2004 22:07:00 GMT

re: Design Guidelines Update: Generics

Jeff — Mon, 15 Mar 2004 22:14:00 GMT

Good post... though a little long. The examples you give at the start are perhaps the best I've seen explaining what generics are.

Some helpful Generics guidelines

ShowUsYour — Tue, 16 Mar 2004 00:22:00 GMT

[.NET]Design Guidelines Update: Generics

おがわみつぎのBLOG — Tue, 16 Mar 2004 02:10:00 GMT

[.NET]Design Guidelines Update: Generics

Generics design guidelines

Jeff Key — Tue, 16 Mar 2004 04:01:00 GMT

re: Design Guidelines Update: Generics

Krzysztof Cwalina — Tue, 16 Mar 2004 06:58:00 GMT

Thomas, thanks for the feedback. I am new to blogging and so I appreciate any comment that can help me understand what's useful to the readers and what's not.

... and I am pushing for a faster release :-) I can asure you that all of us here at MS understand that shipping sooner is a very useful feature.

re: Design Guidelines Update: Generics

Saurabh Jain — Tue, 16 Mar 2004 12:32:00 GMT

You sure are competing with CBrumme when it comes to the long blogging.

.NET design guidelines weblog

Zinoblog — Tue, 16 Mar 2004 20:04:00 GMT

.NET design guidelines weblog

Zinoblog — Tue, 16 Mar 2004 20:04:00 GMT

re: Design Guidelines Update: Generics

Clay — Wed, 17 Mar 2004 13:34:00 GMT

I think the length and content are just fine. I would rather have a larger piece of related material than have it chunked out over ten blog entries.

re: Design Guidelines Update: Generics

W Poust — Thu, 18 Mar 2004 01:26:00 GMT

A good usage guideline we use for STL collections is to make a class out of them (actualy using typedef). It works out great when the collection type changes and those collections are passed as parameters.

If I understood the examples, you are advocating...
void DoSomething(IList<int> param) {...}
void DoSomething2(IList<int> param) {...}

So, you have to do through and modify each menthod signature if the collection changes. Also, in some ways it kind of leaks implementation details.

What I am suggesting is...

class RefreshKeyList : IList<int>
{
}

void DoSomething(RefreshKeyList param) {...}
void DoSomething2(RefreshKeyList param) {...}

Later on if the list type needs to change, there's just one place that needs to be changed. Also, the collection name better describes what it represents.

re: Design Guidelines Update: Generics

Krzysztof Cwalina — Thu, 18 Mar 2004 02:35:00 GMT

W, thanks for the comment. You may be right re the point about aliasing, but only if you are talking about guidelines for application developers, not for reusable library developers. Application developers are rarely concerned with binary breaking changes and only mildly concerned with source breaking changes. They are the only people calling their, often internal, APIs. Changing what RefreshKeyList “aliases” (inherits from or implements in the C# example) is a potentially breaking change. Reusable library vendors (including Microsoft) have a very high bar for such changes. We basically don’t expect to ever change DoSomething(IList<int>) to anything else.
You are right that aliasing improves the name. This is taken into account in the guidelines. See guideline:
Consider returning a subclass of a standard collection from high level APIs, even if you don’t presently plan to provide any customization. If your API returns one of the interfaces (IEnumerable<T>, IList<T>, etc.) or one of the standard collections (Collection<T>, ReadOnlyCollection<T>, etc.) the name of the type will not be as descriptive as possible and also you will not be able to add members to the APIs in the future.
But, there are drawbacks of this approach. For example, if the type represents an input (thus the guideline only recommends it for outputs), you a limiting the callers of the method to the specified type and its subtypes.
I am not sure I understand the comment about “leaking the implementation details”. Could you clarify?

re: Design Guidelines Update: Generics

J. Ambrose Little — Fri, 19 Mar 2004 19:24:00 GMT

Thanks for the post! This is better than the PDC Whidbey docs on generics. I'll definitely be saving a link to it.

A few comments:
1. "Methods should always return Collections returned from methods should be snapshots." This doesn't make sense; I think it's likely a typo, but with a topic like this, you need to be careful to make sense. :)

2. Regarding suggested naming conventions, I think the one-letter option is way out of wack with the other .NET naming conventions and quickly loses its helpfulness when using multiple constraints. I have a couple other options in order of preference.

a) Enable a special character prefix (such as $, #, @, etc.) to denote a type parameter. This would be easy to type (one stroke) and would make them stand out.
b) Recommend a suffix such as Type, TypeParam, or something better (preferably short).

3. Define what you mean by "high-level API."

4. Define what you mean by "snapshot" and "live" collection.

5. Explain type parameter inference or at least reference it in the docs.

6. Don't use "vanilla" and "plain" and "standard" to describe the same thing. Pick one adjective and stick with it and define what you mean by it.

7. Consider expanding the performance considerations to be more specific. For instance, when you say "The CLR shares IL, metadata, and some JIT’d/NGEN’d native code across types/methods constructed from generic types/methods" and "do not enjoy certain JIT compiler optimizations," it'd be nice to get a better understanding of what is shared and not shared and what is not optimized.

8. Consider moving the detailed explanations of generics into separate topics (away from the library guidelines) and just reference them from here. For those who understand this stuff, it'd make it much more readable. Or at least make the stuff collapsable or something like that.

9. Consider explaining how you're optimizing EventHandler<T> and Nullable<T> (maybe in a separate section) to help serve as an example for generic type authors?

10. "Do not introduce new generic types and methods without fully understanding, measuring, and documenting the performance ramifications of their expected use." This is a bit severe and vague. It probably should not even be in the guidelines as it is implicit in any design that you should do these things.

11. I like the common patterns section. This should be easily found for newbies to understand the usefulness of generics.

12. I don't really understand the differences between List<T> and Collection<T>. Please consider expanding on that topic.

13. "When inheriting from ReadOnlyCollection, name it XxxCollection. If you have both read-only and read/write versions of the same collection, name them ReadOnlyXxxCollection and XxxCollection, not XxxCollection and XxxFileInfoCollection" I don't get why anyone would use XxxFileInfoCollection to indicate Read Only.

14. I love Nullable<T>. I agree with Anders on the use; however, I don't get the second option for CLS compliant stuff:

public int Age { get; set; } // this is actually int or null (if Age does not have a value)

int cannot be null..?

Thanks again for the write up. Good stuff!

Generics! Generics! Generics!

Random Thoughts of Jorriss — Fri, 19 Mar 2004 21:27:00 GMT

Generics! Generics! Generics!

Random Thoughts of Jorriss — Fri, 19 Mar 2004 21:29:00 GMT

re: Design Guidelines Update: Generics

Rob — Tue, 23 Mar 2004 00:58:00 GMT

Does Nullable<T> store a separate flag to indicate whether something has a value or is it inferred based on whether or not the value is null?

I have an odd case where I need to differentiate between Not Supplied, and Supplied but Null. Hopefully this is possible.

re: Design Guidelines Update: Generics

Krzysztof Cwalina — Tue, 23 Mar 2004 03:12:00 GMT

J, these are all great comments. I will try to incorporate them into the main document.
As to the type parameter name, we did debate this guideline a lot. We are fully aware that in many scenarios more descriptive identifiers would be better. We finally settled on one letter identifiers as seems they have the edge in the very simple scenarios (like List<T> where the purpose of T is obvious) and these are our main concern when it comes to usability (i.e. we try to optimize for simple 80% scenario and make the rest possible). It also seems like special characters you suggested would be also “out of whack with the other .NET naming conventions”.

“High level APIs” are APIs for mainline scenarios that are usually quite specialized for vertical scenarios. For example, dialog APIs are relatively low level and let you create any dialog you need. FileOpenDialog APIs are high level, easy to use when you work in the “vertical” scenario of opening a dialog to get a file path from the user. I will make it clearer in the main document.

“Snapshot” is when let’s say you get a collection of files in a directory and the collection does not get updated as files are added or removed from the directory; you need to get another copy of the collection to get updates made to the directory. “Live” collection would be updated as the directory changes.

Type parameter inferencing works for generic methods that take a formal method parameter that references (uses) a type parameter. For example Array.Sort<T>(T[] array) takes formal parameter “array” that is of type T[], where T is a type parameter. So now, when Sort<T> is called the type argument does not need to be specified because it can be inferred from the argument (array) passed. For example the following would be legal:
string[] names = string[] { “Foo”, “Bar” };
Array.Sort(names); // compiler knows it’s actually Sort<string> because array is string[]

List<T> is intended for internal implementation, rarely or never visible in public APIs. Collection<T> is intended for reusable library designers to be exposed from their public APIs. The reasons for this are complex. I will try to write it down one day and post it.

The Nullable<T> CLS alternative is indeed not very clear. The point is that in the underlying data source the Age (or int) may be null. In the Customer APIs it of course cannot be null and the logical “nullness” is indicated by the HasAge property.

I hope this helps and thanks again for the through review and good comments.

re: Design Guidelines Update: Generics

Krzysztof Cwalina — Tue, 23 Mar 2004 03:16:00 GMT

Rob, Nullable<T> has two fields: T and bool (to store the nullness). We are currently not supporting tri-state Nullable<T>, i.e. you cannot store null in Nullable and say that it does have a value. The reason for this is that the envisioned purpose of Nullable<T> was to unify the Reference Type world and the Value Type world in terms of how they handle nullness, not to provide yet another way to represent nullness :-)

re: Design Guidelines Update: Generics

Rob — Tue, 23 Mar 2004 03:19:00 GMT

What about Nullable<T> where T is a reference type?

I understand why a tristate nullable value type isn't implemented, but it should be pretty easy to add myself.

re: Design Guidelines Update: Generics

Krzysztof Cwalina — Tue, 23 Mar 2004 06:25:00 GMT

Rob, i am not sure if I fully understand your last post, but we don't allow you to store null in Nullable<SomeReferenceType> and specify that Hasvalue property be true. basically, one you pass null to the constructor of Nullable<T>, the HasValue property get set to false.

re: Design Guidelines Update: Generics

Rob — Tue, 23 Mar 2004 15:09:00 GMT

Ok. So as you said, Nullable exists to unify value and reference types.

I was thinking it'd be more like the Option type in SML or something.

No problem, I can always write my own.

Thanks.

re: Design Guidelines Update: Generics

J. Ambrose Little — Wed, 24 Mar 2004 16:15:00 GMT

Krzysztof,

Thanks for the reply and explanations. Please consider adding your explanation of terms to your document and/or referencing relevant docs (e.g., type parameter inference).

As for the special character convention, I don't think it'd be really out of whack as a language feature. Technically, int, double, float, string, etc. would be out of whack, but they're not because they're part of the language, not so much part of the API. A special character to indicate a type parameter would, in my estimation, fall under that umbrella.

In any case, thanks for expanding on your reasoning there. I'm not sure I can bring myself to use T, but if it's a guideline in the final rev, I suppose I should try. :)

re: Design Guidelines Update: Generics

J. Ambrose Little — Wed, 24 Mar 2004 16:29:00 GMT

Scratch that comment on special characters. It would hose CLS compatibility.. duh..

Why Design Guidelines?

Krzysztof Cwalina — Wed, 31 Mar 2004 08:43:00 GMT

Why Design Guidelines?

Krzysztof Cwalina — Wed, 31 Mar 2004 08:49:00 GMT

Delegate-Based APIs

Krzysztof Cwalina — Tue, 22 Jun 2004 19:44:00 GMT

Delegate-Based APIs

Eric J. Smith's Weblog — Tue, 22 Jun 2004 21:24:00 GMT

Inheritance Generics constraints == the worst documentation experience

Justin Lovell's Blog — Tue, 06 Jul 2004 15:03:00 GMT

re: Design Guidelines Update: Generics

Mateusz Kierepka — Sat, 17 Jul 2004 20:21:00 GMT

:) cool article!

regards from Poland

Ancora sulle novit del Framework 2.0... Generics e altro.

Andrea Zani — Tue, 27 Jul 2004 14:32:00 GMT

re: Design Guidelines Update: Generics

dianying xia zai — Mon, 02 Aug 2004 09:55:00 GMT

[href=http://www.dmoz.net.cn/ wangzhidaquang]
[href=http://www.86dmoz.com/ jingpingwangzhi]
[href=http://movie.kamun.com/ mianfeidianying]
[href=http://www.kamun.com/ dianyingxiazai]
[href=http://music.kamun.com/ MP3 free download]
[href=http://www.pc530.net/ diannaoaihaozhe]
[href=http://www.5icc.com/ duangxingcaixingxiazha]
[href=http://www.dianyingxiazai.com/ dianyingxiazai]
[href=http://www.yinyuexiazai.com/ yinyuexiazai]

Null Object

Web Log di Adrian Florea — Fri, 27 Aug 2004 22:17:00 GMT

Six Questions about Generics and Performance

Rico Mariani's WebLog — Tue, 14 Sep 2004 00:45:00 GMT

Fun with Generics: BindingList and ReadOnlyCollection

Chris Garty's Weblog — Wed, 15 Sep 2004 11:07:00 GMT

Fun with Generics: BindingList and ReadOnlyCollection

Chris Garty's Weblog — Wed, 15 Sep 2004 11:09:00 GMT

.NET 2k5 Generics: Guidelines

Test Bed — Thu, 16 Sep 2004 00:28:00 GMT

Design Guidelines Update: Names of Generic Type Parameters

Krzysztof Cwalina — Wed, 03 Nov 2004 19:04:00 GMT

Design Guidelines Update: Names of Generic Type Parameters

dotRob — Wed, 03 Nov 2004 23:48:00 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 07:44:57 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 07:51:15 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 07:55:04 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 07:56:09 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 08:01:19 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 08:04:53 GMT

Generics

Bryan's Blog — Wed, 03 Aug 2005 18:38:42 GMT

Generics

Bryan Schoening's Blog — Tue, 09 Aug 2005 00:38:54 GMT

Reflection support for generic types in .NET Compact Framework

Nazim Lala — Fri, 09 Sep 2005 01:35:19 GMT

Version 2 of .NET Compact Framework (NETCF) will provide support for parametric polymorphism aka Generics....

Reflection support for generic types in .NET Compact Framework

Nazim Lala — Fri, 09 Sep 2005 01:39:27 GMT

Version 2 of .NET Compact Framework (NETCF) will provide support for parametric polymorphism aka Generics....

Reflection support for generic types in .NET Compact Framework

Nazim Lala — Fri, 09 Sep 2005 01:43:30 GMT

Version 2 of .NET Compact Framework (NETCF) will provide support for parametric polymorphism aka Generics....

Reflection support for generic types in .NET Compact Framework

Nazim Lala — Fri, 09 Sep 2005 01:47:16 GMT

Version 2 of .NET Compact Framework (NETCF) will provide support for parametric polymorphism aka Generics....

CSK

Stanley's Blog — Mon, 17 Apr 2006 23:33:54 GMT

For some time now I have been using the Commerce Starter Kit for one of my websites, Stan's Collectables....

Generics! Generics! Generics!

Jorriss.Net — Sun, 23 Apr 2006 23:38:58 GMT

Generics Design Guidelines courtesy of Krzysztof Cwalina.

Generics Patterns and Practices: ideas and suggestions for when to use generics

The Visual Basic Team — Wed, 28 Jun 2006 00:52:18 GMT

So at TechEd-2006, I gave a chalktalk on generics patterns and practices. I've zipped the content up...

re: Design Guidelines Update: Generics

Bernd Rickenberg — Fri, 17 Nov 2006 19:50:03 GMT

Thanks for a good article.

I'm missing valuable performance information on the generics collection. MSDN only states running times i terms of O() notificaion for a few operations. There does not seem to be consistent information about this topic. I find this very important, when trying to figure out which type to use for a certain application...

re: Design Guidelines Update: Generics

kcwalina — Mon, 20 Nov 2006 20:40:36 GMT

Bernd,

I think the best way to get this information in consistent format is to file a suggestion to add this information MSDN docs. You can file such suggestions at MSDN Feedback center: http://connect.microsoft.com/feedback/default.aspx?SiteID=210.

Generics Patterns and Practices: ideas and suggestions for when to use generics

The Visual Basic Team — Sun, 11 Mar 2007 09:01:16 GMT

So at TechEd-2006, I gave a chalktalk on generics patterns and practices. I've zipped the content up

re: Design Guidelines Update: Generics

Sanjay — Tue, 04 Mar 2008 04:42:56 GMT

Suppose we have classes such as, worker, manager, lifter, ... and these derive from person class.

Now, we need to expose all these as custom collections through an Organization class.

So, do we need to create separate collection class for each of above OR declare a single collection class and all specific collection classes should inherit from it?

What is the best method to expose the single Generic type safe collection for all above base types?

Thanks,

Sanjay

re: Design Guidelines Update: Generics

kcwalina — Tue, 11 Mar 2008 21:12:36 GMT

Sanjay, as a rule of thumb, I would first consider Collection<T> or ReadOnlyCollection<T>, then a custom collection that inherits from them.

You can read more on this at http://blogs.msdn.com/kcwalina/archive/2005/09/23/Collections.aspx and all the details in the Framework Design Guidelines book.

re: Design Guidelines Update: Generics

Michel de Ruiter — Mon, 28 Apr 2008 14:52:56 GMT

Am I the only one having problems printing this page? All pages except the first only contain the last line...

Is there a printer-ready version somewhere, perhaps?

re: Design Guidelines Update: Generics

gary — Thu, 03 Jul 2008 00:15:13 GMT

You say that we should:

"Do use Nullable<T> and EventHandler<T> even over value types. We will work to make these two important generic types as efficient as possible."

Your blog post http://blogs.msdn.com/kcwalina/archive/2005/09/21/ValueTypeEventArgs.aspx mentions how the garbage collector can be stressed if many events are being raised.

Can you explain how you can make the EventHandler<T> more efficient than having a value type. And by value type, do you mean struct, or ints etc. Wouldn't the following always be more performant than creating objects?

// second argument isn't an EventArgs derived type, for performance reasons, avoiding too many allocations

public delegate void MyEventHandler(object sender, int someValue);

public class MyClass

{

public event MyEventHandler MyEvent;

}

Delegate-Based APIs « using …

Delegate-Based APIs « using … — Mon, 20 Oct 2008 13:04:56 GMT

PingBack from http://esersahin.wordpress.com/2008/10/20/delegate-based-apis/

List<T> | hilpers

List<T> | hilpers — Tue, 20 Jan 2009 18:13:20 GMT

PingBack from http://www.hilpers.com/296331-list-t

Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

New Blogger on Framework Design Guidelines

New Design Guideline: Generics

re: Design Guidelines Update: Generics

Some helpful Generics guidelines

[.NET]Design Guidelines Update: Generics

Generics design guidelines

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

.NET design guidelines weblog

.NET design guidelines weblog

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

Generics! Generics! Generics!

Generics! Generics! Generics!

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

Why Design Guidelines?

Why Design Guidelines?

More Recommended Reading

Delegate-Based APIs

Delegate-Based APIs

Inheritance Generics constraints == the worst documentation experience

re: Design Guidelines Update: Generics

Ancora sulle novit del Framework 2.0... Generics e altro.

re: Design Guidelines Update: Generics

Null Object

Six Questions about Generics and Performance

Fun with Generics: BindingList and ReadOnlyCollection

Fun with Generics: BindingList and ReadOnlyCollection

.NET 2k5 Generics: Guidelines

Design Guidelines Update: Names of Generic Type Parameters

Design Guidelines Update: Names of Generic Type Parameters

Generics

Generics

Generics

Generics

Generics

Generics

Generics

Generics

Reflection support for generic types in .NET Compact Framework

Reflection support for generic types in .NET Compact Framework

Reflection support for generic types in .NET Compact Framework

Reflection support for generic types in .NET Compact Framework

CSK

Generics! Generics! Generics!

Generics Patterns and Practices: ideas and suggestions for when to use generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

Generics Patterns and Practices: ideas and suggestions for when to use generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

re: Design Guidelines Update: Generics

Delegate-Based APIs « using …

List<T> | hilpers