Generic type parameter naming convention for Java (with multiple chars)?

In some interfaces I wrote I'd like to name generic type parameters with more than one character to make the code more readable.

Something like....

Map<Key,Value>

Instead of this...

Map<K,V>

But when it comes to methods, the type-parameters look like java-classes which is also confusing.

public void put(Key key, Value value)

This seems like Key and Value are classes. I found or thought of some notations, but nothing like a convention from Sun or a general best-practice.

Alternatives I guessed or found...

Map<KEY,VALUE>
Map<TKey,TValue>

Oracle recommends the following in Java Tutorials > Generics > Generic Types:

> ## Type Parameter Naming Conventions > By convention, type parameter names are single, uppercase letters. This stands in sharp contrast to the variable naming conventions that you already know about, and with good reason: Without this convention, it would be difficult to tell the difference between a type variable and an ordinary class or interface name. > > The most commonly used type parameter names are: > > * E - Element (used extensively by the Java Collections Framework) > * K - Key > * N - Number > * T - Type > * V - Value > * S,U,V etc. - 2nd, 3rd, 4th types > > You'll see these names used throughout the Java SE API and the rest of this lesson.

I'd stick to it to avoid the confusion among the developers and possible maintainers.

Append Type

A good discussion can be found in the comments on the DZone page, Naming Conventions for Parameterized Types.

See the comment by Erwin Mueller. His suggestion makes perfect obvious sense to me: Append the word Type.

Call an apple an apple, a car a car. The name in question is the name of a data type, right? (In OOP, a class essentially defines a new data type.) So call it a “Type”.

Mueller’s example, drawn from the original post’s article:

public interface ResourceAccessor < ResourceType , ArgumentType , ResultType > {
    public ResultType run ( ResourceType resource , ArgumentType argument );
}

Append T

A duplicate Question provides this Answer by Andy Thomas. Note the excerpt from Google’s style guide that suggests a multi-character type name should end in a single uppercase T.

Yes, you can use multi-character names for type variables, as long as they are clearly distinguished from class names.

This differs from the convention suggested by Sun with the introduction of generics in 2004. However:

• More than one convention exists.
• Multi-character names are consistent with other Java styles, such as Google’s style for Java.
• The readable names are (surprise!) more readable.

Readability

>In some interfaces I wrote I’d like to name generic type parameter with more than one character to make the code more readable.

Readability is good.

Compare:

    public final class EventProducer<L extends IEventListener<E>,E> 
            implements IEventProducer<L,E> {

to:

    public final class EventProducer<LISTENER extends IEventListener<EVENT>,EVENT> 
           implements IEventProducer<LISTENER, EVENT> {

or, with Google’s multi-character convention:

    public final class EventProducer<ListenerT extends IEventListener<EventT>,EventT> 
           implements IEventProducer<ListenerT, EventT> {

    public final class EventProducer<ListenerT extends IEventListener<EventT>,EventT> 
           implements IEventProducer<ListenerT, EventT> {

Google style

The Google Java Style Guide allows both single-letter names and multi-character class-like names ending in T.

>5.2.8 Type variable names > >Each type variable is named in one of two styles: > >* A single capital letter, optionally followed by a single numeral (such as E, T, X, T2) > >* A name in the form used for classes (see Section 5.2.2, Class names), followed by the capital letter T (examples: RequestT, FooBarT).

Issues

>“Without this convention, it would be difficult to tell the difference between a type variable and an ordinary class or interface name.” – from the Oracle tutorials, “Generic types”

Single-character names are not the only way to distinguish type parameters from class names, as we’ve seen above.

>Why not just document the type parameter meaning in the JavaDoc?

It’s true that the @param JavaDoc elements can provide a longer description. But it’s also true that the JavaDocs are not necessarily visible. (For example, there’s a content assist in Eclipse that shows the type parameter names.)

>Multi-character type parameter names don’t follow the Oracle convention!

Many of Sun’s original conventions are followed nearly universally in Java programming.

However, this particular convention is not.

The best choice among competing conventions is a matter of opinion. The consequences of choosing a convention other than Oracle’s in this case are minor. You and your team can choose a convention that best meets your needs.

You can use javadoc to at least give users of your generic class a clue. I still don't like it (I agree with @chaper29) but the docs help.

eg,

/**
 * 
 * @param <R> - row
 * @param <C> - column
 * @param <E> - cell element
 */
public class GenericTable<R, C, E> {

}

The other thing I have been known to do is use my IDE to refactor a class breaking the convention. Then work on the code and refactor back to single letters. Makes it easier for me anyway if many type parameters are used.

The reason why the official naming convention reccommends using single letter is the following:

> Without this convention, it would be difficult to tell the difference > between a type variable and an ordinary class or interface name.

I think with modern IDEs that reason is no longer valid as eg. IntelliJ Idea shows generic type parameters with different colors than regular classes.

Code with generic type as displayed in IntelliJ Idea 2016.1

Because of that distinction I use longer descriptive names for my generic types, with same convention as regular types. I avoid adding prefixes and suffixes such as T or Type as I consider them unnecessary noise and no longer needed to visually distinguish generic types.

Note: As I am not a user of Eclipse or Netbeans, I do not know whether they offers a similliar feature.