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>

Solution 1:

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.

Solution 2:

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.

Solution 3:

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.

Solution 4:

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.