Rename generic parameters K and V to Key and Value in Treemap

[mcpherrinm]

One of the goals for Rust's standard library is to be readable. In my opinion
terse generic variable names are one of the worst offenders in this regard:
Nobody need argue about the value of good variable names in general, but for
some reason we accept them in generics and lifetimes.

Especially in cases like this, good names are absolutely available, so let's
use them.

[lilyball]

Effectively all of our precedent here is for using terse, typically single-letter, generic type names. If we're going to start moving away from that, I think this needs some discussion instead of just doing the replacement in Treemap.

Personally, it seems obvious from context that K and V represent the key and value type. But I understand the desire for more descriptive names. If we are going to start making this change, I'd rather see an example of a type where the renaming actually has an obvious increase in readability, as opposed to a mapping type where K/V are already widely-understood.

[mcpherrinm]

I picked Treemap pretty much at random as a sample. K/V are mostly obvious but I still see value in using full names. In a lot of ways I sent this pull request to gauge opinion as much as to have the change accepted.

HashMap is probably a better example, since I've seen a bunch of people confused about the H parameter and S in Hasher<S>. I could do that change instead.

The problem I have with terse variables is that they are exposed to the user: they may be inferred a lot of the time, but they show up in documentation and sometimes users have to provide them.

[alexcrichton]

Although the style guide does not explicitly say it, I believe the conventional style is for all type parameters to have short (mostly one-letter) camel case names.

cc @aturon

[sfackler]

One benefit of terse type parameter names is that they're visually distinguishable from types.

[mcpherrinm]

The conventional style is for one-letter names, and I think this is wrong, especially for types exposed to users. This is one of my biggest peeves with the language's readability, along with too-verbose lifetime syntax.

Is being distinguishable from types by being completely unreadable a goal? Type parameters are effectively types when writing code, and if you have a reason to care what it is, you have to look at the type signature anyways.

I could be wrong here. Maybe nobody will be confused by Widget<Q, S, T, N, P>. I come from a mathematics and theory background where such things are terribly common, so I'm used to it. I still think it's a bad idea.

[chris-morgan]

As type parameter names go, T, K and V are well understood and conventional. I would say -1 on changing K and V when they mean key and value in mapping context, or T when it is an arbitrary type, but most other ones I would be in favour of expanding to something more meaningful.

[bstrie]

I don't think that readable standard lib source code is a priority for 1.0, but readable docs certainly are. Tagging as a doc bug and paging @steveklabnik

[steveklabnik]

This is certainly a conventions-related issue, and we should be clear about what to expect. T certainly means a type of some kind, but other ones are murky. K/V is pretty common for hash maps.

In general, +1 to longer names. But this is gonna require some discussion/thought.

[thehydroimpulse]

-1. K and V type parameters are well understood. I don't think you can get that much more descriptive about type parameters other than single letters. The same thing applies to lifetimes (although lifetimes are much less capable at having descriptive names)

[mcpherrinm]

If we treat this as a documentation bug:

I propose we add the attributes #[docname(K, Key)] to generics. Then, instead of printing K as the variable name in the documentation, we can print Key!

This saves developers from the arduous task of typing ey two or three times and still leaves us with usable documentation!

[thehydroimpulse]

+1 on @mcpherrinm's latest proposal on having #[docname].

[thestinger]

I think having one name in the code and one in the documentation would be an overly complex solution to what should be a simple problem. If we're going to use longer names, it should be a consistent style rather than just a change for TreeMap / TreeSet and it should be the same for the documentation and the code. I don't have a problem with using longer names in most cases.

[ghost]

-1. K and V are well understood in this context. In most other contexts, one letter names are completely fine. Descriptive names should only be used when necessary. 100% one letter names, or 100% descriptive names would both be dogmatic and less than ideal in many circumstances.

[mcpherrinm]

Focusing on the fact that you know what K and V are in this context is missing the point.

[mcpherrinm]

Well, I suppose this is a pull request, so not entirely missing the point. I guess I should choose a more appropriate venue for the style discussion.

[UtherII]

I like more descriptive names, but I like being able to distinguish parameters from actual types at first sight too.

A new convention for parameter type may grant both. Maybe prefix them with "_"

[FreeFull]

We could have the type parameters show up as K and V in the documentation, but have hovering over them present a tooltip with a longer name, and possibly an explanation.

[nikomatsakis]

I'm torn. In general, I agree that shorter names are harder to read. But I've found in practice that when I use long names for generic parameters, the code becomes paradoxically less readable to me. Perhaps it's because I can't distinguish concrete from generic types. Maybe a convention like KEY and VALUE would help. I don't know.

Also, I tend to agree that T, U, V (or A and B) for "any old type" or "element of some container" is more-or-less ideal, and readability is not improved by using TYPE.

[adrientetar]

-1 It adds clutter to have Key and Value written in the middle of the rest, K and V make them distinguishable from words. Besides I think that those who use Treemap know what Key and Values are – nothing that docs cannot clear up anyway.

The doc_name attributes thingy adds code bloat imo – solely for some sort of aliases... it can simply be explained in the doc.

[lilyball]

If type parameters are not implicitly obvious (i.e. if you'd be tempted to use doc_name), just write in the docstring what the meaning of the parameter is.

[netvl]

-1. It is a very widespread practice to use single one-letter names for type parameters, so they are visually distinctive from actual types. When type parameters have long names, it can be very difficult (especially without any navigation support from IDE/editor) to find out what some type is.

There is a precedence for adopting a convention for long names for type parameters in Ceylon language, and IMO it looks ugly and does not add readability at all.

Moreover, this is only a "problem" when you read the code. When you use a trait/struct, for example, from standard library, using only its API docs as a reference, it is not a problem at all, because type parameters should be explained in the docs anyway.

[mcpherrinm]

It seems like there's not much support for naming generic parameters, so I'll go ahead and close this.