Design Guidelines Update: Names of Generic Type Parameters

Статья
11/03/2004

After receiving lots of feedback from internal and external community (see here for example), we decided to modify the generic type parameter naming guidelines. The previous guidelines allowed only single letter type parameter names. The new guidelines allow and even encourage descriptive names.

Here are the new guidelines.

Names of Generic Type Parameters

Do name generic type parameters with descriptive names, unless a single letter name is completely self explanatory and a descriptive name would not add value.

public interface ISessionChannel<TSession> { … }

public delegate TOutput Converter<TInput,TOutput>(TInput from);

public class List<T> { … }

Consider using T as the type parameter name for types with one single letter type parameter.

public int IComparer<T> { … }

public delegate bool Predicate<T>(T item);

public struct Nullable<T> where T:struct { … }

Do prefix descriptive type parameter names with “T”.

public interface ISessionChannel<TSession> where TSession : ISession {

TSession Session { get; }

}

Consider indicating constraints placed on a type parameter in the name of parameter. For example, a parameter constrained to ISession may be called TSession.

Also, the BCL team is now considering several renames to the BCL generic types. We are still counting votes and it’s too close too call :-), but here is the provisional list:

EventHandler<T> : new name EventHandler<TEventArgs>
Converter<T,U> : new name Converter<TInput,TOutput>
Dictionary<K,V>, IDictionary<K,V>, KeyValuePair<K,V>, SortedDictionary<K,V>, SortedList<K,V> : new name something like Dictionary<TKey,TValue>. (same with all the related nested collections and enumerators)
KeyedCollection<K,T> : new name KeyedCollection<TKey,TItem>

I would like to thank all of those who provided feedback on this issue.

Thanks!

Comments

Anonymous
November 03, 2004
I think the new standard is much better, and the key is the use of the "T" prefix, which can be read as "Type of".
Anonymous
November 03, 2004
As I don't like prefixes, I would prefer to use a "Type" suffix for generic type parameters.

Doesn't look Dictionary<KeyType, ValueType> better than Dictionary<TKey, TValue>?

Classes have no "C" prefix but interfaces start with "I". Why would you want to add to this naming inconsistency?
Anonymous
November 03, 2004
Rather as "I" in interface (IConvert - "interface-convert") name can be read as TKey = "template-key"
But Dictionary<K,V> looks simple and good!
Better keep "K", "V" as key/value parameters and others prefix with "T"
Anonymous
November 03, 2004
I am very strongly opposed to these changes. The longer names do not provide anything useful. I have been using Beta 1 since it was released and am happy with the current system.

There is already a system to use to describe the type:
/// <typeparam name="T">...</typeparam>

Why should we duplicate this information?

I understand that not everyone will be using VS with it's built-in Intellisense. But even if you use Notepad, which I do sometimes, I think most people will still need to lookup the type names in the documentation, where the details should be written already, so the longer type name still won't be of any extra value.

Those of us with C++ backgrounds, which I think is a significant portion of C# users, are probably more used to short template types T etc. These longer names alienate such users.

The proposed examples such as EventHandler<TEventArgs> and Dictionary<TKey, TValue> are ugly... I fear that these will be so wordly that I will need to refer to the documentation on a regular basis just to figure out what the BCL team decided to use.

Type names can not be localized for other languages, while documenation (<typeparam>) can be.

Just use the appropriate <typeparam> tag and save us the frustrations that this introduces. I can not imagine a single positive advantage that these longer type names provide, but I can think of many negative aspects of these changes.

Please, please reconsider this.
Anonymous
November 03, 2004
The comment has been removed
Anonymous
November 03, 2004
The comment has been removed
Anonymous
November 03, 2004
I was just browsing this blog post (half asleep) until I read the lines

* EventHandler<T> : new name EventHandler<TEventArgs>
* Converter<T,U> : new name Converter<TInput,TOutput>

and I was awake immediately, thinking to myself "wow, this is SO much better!".

But I must admit that I'm someone who's not afraid of using long names (even for local variables) since writing code in a proportional font.

Single letters may be nice when the abbreviation is obvious (T = type, k = Key, V = value), but things are not always that easy; e.g. I wouldn't like to use I for item or input, or O for output.
Anonymous
November 03, 2004
Roland Weigelt wrote:

> Single letters may be nice when the abbreviation is obvious
> (T = type, k = Key, V = value), but things are not always that easy;
> e.g. I wouldn't like to use I for item or input, or O for output.

That is why there is the <typeparam> tag. You can describe and explain what T means to your hearts content. Also, Intellisense displays that information when you're typing. And if you're not using VS and can not use Intellisense, the longer type names still will not help you because you must look it up in the documenation which should have even fuller information. I think Microsoft is making a serious mistake here.
Anonymous
November 03, 2004
I like this new idea very much.
Anonymous
November 03, 2004
The bracket and the capitalized first letter are enough.

The names could be better though: "TInput"?
Theres no harm in renaming them if the new names are better.

Some ideas...
EventHandler<T> : new name EventHandler<EventArgs>

Converter<T,U> : new name Converter<Source,Target>
or
Converter<T,U> : new name Converter<Source,Destination>

Dictionary<K,V>: new name Dictionary<Key,Value>
Anonymous
November 03, 2004
This post really surprised me. Regarding the guidelines, naming conventions, class organization, etc., I think Microsoft has always done a great job so far. But NOT this time. This change is totally inappropriate. Please keep all those single-letter type parameters. They're so perfect. To me, Dictionary<K,V> looks much simpler than Dictionary<TKey, TValue>, yet still easily understandable. Plus, using single-letter (T, K, V) will keep the Generics namespace consistent throughout all classes. Otherwise, it will be bloated with numerous parameter names: TInput, TKey, TValue, TEventArgs, TOutput,... sigh
Anonymous
November 03, 2004
I fully agree with dotnetjunky! Microsoft is making a terrible mistake; it was perfect before. But there is no need to repeat him/her; just re-read the message.
Anonymous
November 03, 2004
The new guidelines look very akward. I agree with some of the comments made here. Keeping single letters will make it for a much cleaner solution. If the consumer needs further explanation about a parameter, they can look at the xml documentation!
Anonymous
November 03, 2004
The comment has been removed
Anonymous
November 03, 2004
The comment has been removed
Anonymous
November 03, 2004
The comment has been removed
Anonymous
November 03, 2004
I like the new guidelines. They make template declarations self-documenting where needed, without making them longer where additional information is not needed.

From the comments above I get the impression that some people never think of others who may have to read or use their code. Maybe you are happy with alphabet soup parameters but when IntelliSense pops up I'd rather have a descriptive name for my template parameters...
Anonymous
November 03, 2004
The new guidelines are great! Thank-you Microsoft. No, people, the old single-letter scheme was not perfect at all. In fact it was awful from every single point of view. It was perfectly awful. The arguments I see on this page praising the old scheme inevitably fail to take into account important aspects of the problem. I have spent many months pointing out the pitfalls of the old approach; I refer you to http://lab.msdn.microsoft.com/ProductFeedback/viewFeedback.aspx?feedbackid=3cee09d8-3b82-4c5f-83a4-be52ba9b9e98
If you like single letters, I ask you to please take the time to review the arguments we've had on the above link. Microsoft - way to go!
Anonymous
November 03, 2004
I like proposed change. But in general - I do not care.

I like it because it will allow reading generic classes better.
"Here we have a IDictionary with string keys and Customers values"
This will allow user to see correct order of type arguments.

I do not care - because I prefer MSDN documentation improved to document all those arguments/parameters, usage scenarios, alternatives, limitations etc..
As well - there are nothing better that exceptions from rules and guidelines. If you will decide to keep K,V - nothing wrong will happen ;-)

T preffix is okey for me. I'm big Delphi/Pascal fan ;-)
Anonymous
November 03, 2004
This is much better. I've written some slightly complex generic code. The argument about longer type argument names making generic type usage easier is a STRAW MAN argument - it's easy to criticize that by saying "intellisense does that already".

That isn't what's improved by this change in the guidelines.

Longer generic type names make READING GENERIC CODE easier.

When you've got generic types, and then generic static methods which take these generic types as parameters and return special classes of generic types as results, it's extremely easy to lose track of what U and V means in the context of a generic type as an argument and as a result, or as a parameter to a generic type, or as a parameter to a generic type used as a result. There isn't enough semantic information in short type argument names to write legible generic code.

Compare this:

---8<---
delegate T Generator<T>();
delegate T Unary<T, U>(U value);
delegate T Binary<T, U, V>(U x, V y);

static class //...
{
public static Generator<T> BindUnary<T, U>
(Unary<T, U> target, U value)
{ // ... }
}
--->8---

With this:

---8<---
delegate TResult Generator<TResult>();
delegate TResult Unary<TResult, TArgument>(TArgument value);
delegate TResult Binary<TResult, TFirst, TSecond>(TFirst x, TSecond y);

static class // ...
{
public static Generator<TResult> BindUnary<TResult, TArgument>
(Unary<TResult, TArgument> target, TArgument value)
{ // ... }
}
--->8---

-- Barry Kelly
Anonymous
November 04, 2004
Please tell me this is a beginning-of-November joke? The BCL team isn't going to seriously recommend these guidelines?
Anonymous
November 04, 2004
Other than the T prefix, I like the change. I can live with the T prefix, but see it as unnecessary. Descriptive names are much preferable to one letter mnemonics.

Thanks for listening!
Anonymous
November 04, 2004
Chris Nahr wrote:

> Maybe you are happy with alphabet soup
> parameters but when IntelliSense pops up
> I'd rather have a descriptive name for my
> template parameters...

This is exactly what the <typeparm> tag is for. It is one of the XML documenation tags. With it, you can describe what type T does. And IntelliSense DOES pop up with this information. Please try it.
Anonymous
November 04, 2004
Michael Giagnocavo wrote:

> Please tell me this is a beginning-of-November
> joke? The BCL team isn't going to seriously
> recommend these guidelines?

Those were my initial reactions as well, but they seem serious about it.

Krzysztof: Please answer me this. Is Microsoft still open to feedback to undo these new guidelines? Or has Micrsoft 100% made up their mind and no end of complaining will change anything anymore? I ask because this is very important to me, but I do not want to waste my time if the decision has been made already. Please let us know. Thanks.
Anonymous
November 04, 2004
The comment has been removed
Anonymous
November 04, 2004
Ore Sama: Awesome. I didn't know there was a typeparam tag! Then there's no tool work being saved (i.e., no extra attributes/data to handle). This whole thing is really dumb now, considering in this light.

As far as MS being open, of course they are. I think perhaps people just ignored this cause they didn't think MS was gonna change (I would have bet 100:1 MS wouldn't do this) -- so put out a cry to everyone you know to complain to MS. They'll fix this.
Anonymous
November 04, 2004
The comment has been removed
Anonymous
November 04, 2004
The comment has been removed
Anonymous
November 04, 2004
Krzysztof's point about tool support is a good one. Are XML comments supported for all language compilers in all IDEs? The .NET Fx SDK is available separately from VS .NET, so the BCL team need to consider the implications beyond a single tool.
Anonymous
November 04, 2004
I seriously dislike the "T" prefix. (Because I'm a Delphi programmer, and it screams something different than what it's trying to.)

Go with either a "Type" suffix, or use all caps. Those would both be good conventions. Or maybe a "G" prefix, for "generic". But... please, not T.
Anonymous
November 04, 2004
The long names are much better IMO! Thanks for listening!!

John
Anonymous
November 04, 2004
Re IntelliSense: I'm not talking about knowing what the currently highlighted parameter does; I'm talking about knowing what all the parameters do. Remember, long type parameter names are primarily useful when you have lots of them.

Also, what Frank Hileman said. Is the presence of a long description in the XML comments an excuse to use single-letter method parameters? If not, why should this argument suddenly apply to type parameters?

And like many others said, there are situations where you want to read code outside of Visual Studio; and IntelliSense is of no help while developing a complex generic type.
Anonymous
November 04, 2004
I agree with Frank - XML documentation + Intellisense should be used as an aid, not as the solution. Note that you would still want to use the <typeparam> tag for type parameters that have descriptive names, in order to provide a fuller description. As an example, just look at method parameters in any of the BCL methods - they have descriptive names, as well as full sentences describing their use via Intellisense. As with method parameters, so with type parameters.

Another thing, sticking with single letters and relying on <typeparam> doesn't solve the myriad other problems that come with single letters. See my 12 points in favour of descriptive names on the FDBK10547 suggestion page for a list of these problems.

I think that people who want to stick with single letters are just looking at the relatively simple generic situations we have at the moment. As more advanced generic code gets written going forward, the single-letter scheme soon runs out of stream, whereas the descriptive-name scheme is far more future-proof.
Anonymous
November 06, 2004
Names should express intent - that removes the need for additional comments. I thought it wasn't just Agile that proposed this, IIRC its been around since the first edition of Code Complete.

So rename the parameters to express intent (I lived with uniformative abbreviations too long in C++).

Personally I would lose the pseudo-Hungarian too. I guess we are stuck with the naming convention on interfaces (why I don't know, a C# interface is not a class as in C++ so we don't need a naming convention for it). We'll be back to m_ and dCount before long if we keep this up. Have we learned so little?
Anonymous
November 06, 2004
The comment has been removed
Anonymous
November 06, 2004
People continue to suggest that generic parameter types and variable naming conventions should be the same for clarity. I think you are mistaken. Of course I support descriptive variable names, but generic type names are another issue. Do not forget that the generic type will also have a variable of that type which should already have a descriptive name. For example, in Set<T>, you would have a private member array called "elements" which is of type T. In the rest of the class, you refer to "elements" and not what "T" is anymore. The point is that any generic parameter will have an associated variable to go along with it and that variable is what needs a good descriptive name, not the generic parameter. Changing it to Set<TElement> with private TElement[] elements does not add any new useful infomation to me since I will be using "elements" and not "TElement" in the rest of my code. It is redundant.

It is obvious that with or without these guidelines, many people feel strongly about the issue. I for one will continue to use the single-letter naming convention. It has worked well in C++ templates for about a decade and is most familiar and comfortable to me. People should use what they prefer. However, the BCL is shared by all. I am disappointed with Microsoft's guidelines, but at least it will not not affect my code.
Anonymous
November 06, 2004
AT: ";-) This stupid idea must show why single-letter idea naming is not good."

Well, I think it only shows a stupid idea ;-).

"Additionaly - names of temporary variables are recomened to derive from their type name - so for T and V temporary variable names will not be good. "

Huh? If you're naming vars stuff like s, d, f, etc. that's most likely not good. So is "tempDouble" or "tempString", generally speaking. Try to give them some meaning, other than the type. (Obvious exception for common well-known var names, like i for loops).
Anonymous
November 07, 2004
Keep the descriptive naming.
I really am shocked that there are people who are still supporting naming things with a single character.
Anonymous
November 07, 2004
> I really am shocked that there are people
> who are still supporting naming things
> with a single character.

Who are these "people"? The designers of the STL, most of the C++ community (in relation to templates), Microsoft up until now etc.

What are these "things"? Not variable names, but generic type parameters. They are generic so they should not have a specific name.

I am shocked that there is so large a group of people who can so easily throw away a decade of experience and tradition. Generics are new, but I wonder how many of these people have real experiece with templates.
Anonymous
November 07, 2004
> Who are these "people"? The designers of the
> STL, most of the C++ community (in relation
> to templates), Microsoft up until now etc.

How can you claim to know the thinking of "most of the C++ community (in relation to templates)" ?

> What are these "things"? Not variable names,
> but generic type parameters. They are
> generic so they should not have a specific
> name.

Shouldn't a type parameter's name indicate its use within the generic class or method to which it's passed ?

btw: a type parameter is not "the generic". The generic is the thing (method, class, etc.) that it's passed to. The generic uses type parameters for specific purposes; these purposes should be indicated by descriptive names. Whoever first thought that single letters were OK was wrong.

> I am shocked that there is so large a group of people who can so easily throw away a decade of experience and tradition.

This group of people is improving on the experience of C++ templates. As regards tradition... we don't want tradition to stand in the way of progress.

> Generics are new, but I wonder how many of these people have real experiece with templates.

You don't know and I don't know. Maybe a lot of "these people" have had real experience with templates! I know I have.

Microsoft generics, long thought-out and very carefully designed, improve on C++ templates in every way. I can say 'every' way now that these naming guidelines are in place.
Anonymous
November 07, 2004
This is great! I was already using exactly this convention for my own generic code.

I'm usually very strict about following the guidelines, but this was one area where I felt very strongly that the guidelines were inappropriate, and that it was ok for me to deviate from them.

Very happy to see this change.
Anonymous
November 07, 2004
> How can you claim to know the thinking of
> "most of the C++ community (in relation to
> templates)" ?

I did not claim to know anyone's "thinking". I base that comment from my experience of about a decade of experience with templates, reviewing fellow programmer colleagues' code, and at least a dozen books on template usage and algorithms over the years. While on the rare occasion I have encountered the exceptional programmer or book that used longer template names, single letter template names are by far the norm in my experience. Your experience may differ, but I can not comment on that.

> Whoever first thought that single letters
> were OK was wrong.

Who are you to decide what is right or "wrong"?
What is your criteria to determine right or "wrong"? Do you have any specific reasons to declare this first person "wrong"? Or do you not need reason to make such a summary judgement?

> As regards tradition... we don't want
> tradition to stand in the way of progress.

Who is "we"? Do you claim to know the thinking of others? Do you have any specific reasons to dismiss tradition? Or do you not need reason to backup your statements?
Anonymous
November 07, 2004
David, I'm not afraid to state that single-letters are wrong-headed because in my experience of using C++ templates, they've proved to be a nightmare. Unreadable code is the result. I've followed the arguments for/against single letters, and I've yet to see one good argument for their retention. I've soon loads of good arguments against their use.

As regards the issue of tradition, instead of trying to answer all 4 of your questions, let me ask you a simple one... Do you want to let tradition to stand in the way of progress ?

David, what I'd love you to do most of all is come up with a really good technical reason why single letters are preferable, over and above the "we've always done it that way" argument.
Anonymous
November 08, 2004
> "...they've proved to be a nightmare.
> Unreadable code is the result.

"proved"?
What is your evidence?
Can you document this proof?

It may be a nightmare to you, but it has not been for me. A single capital letter is an immediate hint to me that it represents a generic type parameter. With longer type names (not variables, mind you), it is not so immediately distinguishable. For this reason, the style that you suggest is not as readable.

> I've followed the arguments for/against
> single letters, and I've yet to see one
> good argument for their retention. I've
> soon loads of good arguments against
> their use.

Nor have I seen any convincing arguments for longer names. Perhaphs we will have to agree to disagree.

> As regards the issue of tradition, instead
> of trying to answer all 4 of your questions,
> let me ask you a simple one... Do you
> want to let tradition to stand in the way
> of progress ?

Instead of answering even a single one of the questions, you will brush them to the side and ask a new question? It is difficult to have a two-sided conversation with you when you continually ignore questions and omit your rational for statements.

Nevertheless, I will try to answer your question. I do not see what you are trying to advance as "progress". Rather, I see it as just the opposite. I know of no convincing advantages to it. I listed one reason why it is less readable above. No, I do not think tradition is standing in the way; I think it was a good thing in the past and continues to be a good thing today as well. Nothing has changed nor should it.

> David, what I'd love you to do most of
> all is come up with a really good technical
> reason why single letters are preferable,
> over and above the "we've always done it
> that way" argument.

That is exactly what I would like you to do. Until now single letters have been the norm. It is a tradition which you do not seem to be denying. I do not feel that the I need to defend the past and argue for the status-quo. Why should we dismiss the past, our experience and instincts, and settle with a new style? Please provide some "really good technical reason[s]" why longer names should be preferred.

You want me to ignore the "we've always done it that way" argument. However, I think that is the main issue here. If C++ never had templates and generics were being introduced without any historical connections, I do not think we would be having this conversation. The slate would be clear and we could create new conventions. There would not be an established style which I have grown accustomed to. Nor would I instinctively look for single letter instead of longer type parameter names. But that is not the case. C++ template naming styles deeply influence even these guidelines. Notice for instance the T-prefix that some have argued against. Tradition can not be denied or ignored.

The BCL is shared by all. This is both a blessing and a curse. I was perfectly happy with the naming through Beta 1. But apparently others such as yourself were not very pleased. I have no problem with others using longer type parameter names in their own code. No one will force me to use it. However, I must use the shared BCL. That is why I am so strongly opposed to Microsoft changing their naming guidelines.
Anonymous
November 08, 2004
OK David. Here goes:-

> Who is "we"? Do you claim to know the
> thinking of others? Do you have any specific > reasons to dismiss tradition? Or do you not
> need reason to backup your statements?

When I said "we don't want tradition to stand in the way of progress" I meant that in the same way as I might say "we don't want cars to run us over". In neither case do I claim to know the thinking of others, and I don't claim to speak for everyone. But I hope that none of us want to be run over, and I hope that, with something as new and fast-evolving as computer programming practice, none of us want to let tradition (in the form of "we've always done it that way so let's not change") stand in the way of real progress.

> Nor have I seen any convincing arguments for
> longer names.

Please go here:-
http://lab.msdn.microsoft.com/ProductFeedback/viewFeedback.aspx?feedbackid=3cee09d8-3b82-4c5f-83a4-be52ba9b9e98
and read. I know it's a lot to wade through, but a friend of mine recently told me that it took him an hour. That's not too bad.
Anonymous
November 08, 2004
Axon: I have read it. I generally check the FBC daily to review bugs and suggestions. Let me repeat myself: "Nor have I seen any convincing arguments for longer names." Which parts specifically do you agree with? There are arguments both for and against it there. Do you have any arguments of your own?

While on the issue of FDBK10547, please note that it has a rating of 3.70. With 1 being the lowest (Not Important) and 5 the highest (Very Important), general opinion for this issue seems rather neutral with no strong consensus. I voted a 1 several months ago because I was happy with the current implementation and did not desire any change. However, a significant few individuals (far less than 200 people who voted) have been extremely vocal about the issue and have apparently gotten Microsoft to change the guidelines. The issue is not maked as Closed so I am unsure if they review it anymore. However, I can be vocal if need be. And others here have been as well.

We still disagree about "progress". Whether you do not understand my explaination or choose not to understand it I do not know.
Anonymous
November 08, 2004
David: I agree with virtually every point made in favour of descriptive names. And I can't remember there being a single argument for retaining single-letters that I agreed with. For me, the most important argument is that a type parameter is used for a specific purpose within a generic type or method, and that usage is best indicated by a descriptive name, not T, U, V, W, X, Y, Z.

As regards tradition vs progress, you've stated that if it wasn't for the tradition of single letters "There would not be an established style which I have grown accustomed to.", and I understand that. Trivial example: I thought that the introduction of the 'X' button to close a window in Windows 95 was a big mistake. I was too used to clicking top-right to maximize, and thought that I would end up accidentally closing windows all the time. Well, it turns out I got used to the new scheme pretty quick, and it was fine.

We all want to hold on to what we know and feel comfortable with. There have been many times over the years where Microsoft have introduced a change that I felt initially uncomfortable with, only to find that in the end it was an improvement. I hope and trust that you will find this with the new type parameter naming, assuming you go along with the new guidelines. Even though you are very much opposed, I do hope you'll give them a shot.
Anonymous
November 08, 2004
I agree with David. We C++ programmers have been using templates for a long time and the single letter naming convention is the most common. Please do not suggest that we change that now for the new programmers.

Please consult more of the community. Perhaps an article on MSDN. I am not a regular blog reader and was surprised when I was forwarded these new guidelines by a friend. I do not think many people like myself are aware of these changes and thus have not had reason to comment about it. Hopefully it is not too late to reconsider.
Anonymous
November 08, 2004
The comment has been removed
Anonymous
November 08, 2004
I support the descriptive names. (Somehow I feel like I have to argue not to change it back...) They make the generic classes just a little easier to use. Plus, the single-letter names look out of place within the rest of the framework.
Anonymous
November 08, 2004
What is descriptive about longer names? Lets think this through in some context. I gave two examples earlier:

Set<T> and Set<TElement>.

One of the rationals given by Microsoft is to create a solution that does not rely on a tools such as VS's Intellisense, so we must consider a regular text editor. There are at least four cases to consider here:

1) Instantiate Set<T>/Set<TElement> in a text editor (no tools).
2) Instantiate Set<T>/Set<TElement> in Visual Studio (includes tools).
3) Define generic class Set<T>/Set<TElement> in a text editor (no tools).
4) Define generic class Set<T>/Set<TElement> in Visual Studio (includes tools).

In case 1), the programmer will begin by typing "Set<". Whether the type parameter is T or descriptive TElement, the programmer can not tell. He or she will need to refer to external documentation for further details since the longer name can not provide any hints here. Conclusion: descriptive or not is not an issue.

In case 2), the programmer will begin by typing "Set<". At this point, both the descriptive name and the descriptive information in the XML documentation tag <typeparam> will be displayed. Conclusion: a long descriptive name is redundent and most likely will not be as descriptive or as readable as the <typeparam> tag can be.

In case 3), the programmer will have a private variable T[] elements or TElement[] elements. When designing the code, he or she will refer to the variable "elements" and not type T/TElement (please understand this point; each generic parameter should have a corresponding variable--name this well). Conclusion: a long descriptive type parameter name will make no difference here.

Case 4) should be the same as 3) as well. Same conclusion.

For people who use a regular text editor without external tools support, a longer descriptive name will not be visible to them. They will need to refer to the external documentation (MSDN) which should have plenty of detailed information far exceeding the long descriptive name.

For people who use Visual Studio or an equivalent application that reads metadata, he or she will be able to read the XML documentation which should provide a detailed description as well as a shorter, less descriptive multi-letter name.

Longer named type parameters should not make a difference for people who use regular text editors. It should only make a difference for people who use VS-like applications, but the XML documentation is also available at the same time and should provide more descriptive information than a longer name can provide.

I desire readable and understandable code. However, as examed above, the cases that longer type parameter names can be of any use, XML documentation should be available as well. Lets refactor the duplication out and use the right tools for the right jobs.
Anonymous
November 08, 2004
I'm mildly disappointed that the guidelines have settled on a "T" prefix rather than the "Type" suffix which seemed to have a reasonable degree of support. However, it's great - and much more important - that the long type name convention has been adopted.

I read the rationale for choosing the T prefix, and I think the same arguments would have applied equally to the "Type" suffix, but I can live with it.
Anonymous
November 09, 2004
I would just like to point out that we don't recommend that types like Set<T>, List<T>, Collection<T>, etc. use descriptive parameter names. If T is completly self explanatory (for example it's the only type parameter and it can be anything), single letter parameters are fine.
Anonymous
November 09, 2004
Perhaps my example was less than ideal. So replace the example with Dictionary<K,V> / Dictionary<TKey,TValue>. However, nothing changes in the argument; all four cases and their conclusioins remain the same. With or without tool support, longer type parameter names should not make a different. Please re-read the four case analysis for details.
Anonymous
November 09, 2004
As said in MSDN PFC, I vote for the "Type" suffix. It's more readable than the "T" prefix. But if there was the choice between the "T" prefix and the "short" names like 'T' und 'U', I'd vote for the "T" prefix.
Anonymous
November 09, 2004
Generic タイプパラメータの命名規則
Anonymous
November 15, 2004
Descriptive annotation as part of generic type should be part of documentation and not part of the generic type declarations. This will be useless, cumbersome and unnecessary extra code.
Anonymous
November 23, 2004
Krzysztof, I think the T prefix is a good compromise between visually setting off type parameters and allowing meaningful parameter naming. Thanks!
Anonymous
December 29, 2007
PingBack from http://cars.oneadayvitamin.info/?p=793
Anonymous
March 04, 2008
The newest version at MSDN http://msdn2.microsoft.com/en-us/library/ms229040.aspx does no longer contain: Do prefix descriptive type parameter names with the letter T. Is there a specific reason for this?
Anonymous
March 11, 2008
Nere, thanks for pointing this out. I will follow up with the MSDN folks. This is not intentinal, AFAIK.
Anonymous
March 15, 2008
PingBack from http://babynamesongsblog.info/krzysztof-cwalina-design-guidelines-update-names-of-generic-type/
Anonymous
December 07, 2008
Krzysztof, what would you prefer for the signature of the function composition operator/function? (In all cases the implementation is return x => g(f(x)); by the way) public static Func<A,C> Compose<A, B, C>(Func<A, B> f, Func<B, C> g) versus: public static Func<TSource, TResult> Compose<TSource, TIntermediate, TResult>(Func<TSource, TIntermediate> f, Func<TIntermediate, TResult> g) versus (taking a hint from Func<T1,T2,TResult>): public static Func<T1, TResult> Compose<T1, T2, TResult>(Func<T1, T2> f, Func<T2, TResult> g) Coming from a functional (Haskell) background/mindset, the first looks natural to me, and I think that's also the way they do it in F#. The second will run into problems as soon as you try to add a third function (TIntermediate1 and 2? Yuck.) The third is a fairly reasonable alternative which still sets apart the result type but otherwise is still compact. What do you think?
Anonymous
December 09, 2008
2 and 3 seem both reasonable. I would probasbly lean toward #3.
Anonymous
April 26, 2009
Spot on, it's about time this change was made. Hopefully pleading cry babies will shut up now.
Anonymous
June 16, 2009
PingBack from http://topalternativedating.info/story.php?id=11635
Anonymous
June 18, 2009
PingBack from http://firepitidea.info/story.php?id=1480

Поделиться через

Design Guidelines Update: Names of Generic Type Parameters

Names of Generic Type Parameters

Comments

Дополнительные ресурсы