Violating java generic generics naming convention?

Question

I have an interface whose declaration is this:

/** * @param T - the type of entity. * @param C - the type of entity container will be returned. */ public interface FindByNamedQuery<T extends Serializable, C extends Collection<T>> extends Command { C executeNamedQuery(String namedQuery); } 

I wonder if I can (should) break the Java naming convention to do this:

 public interface FindByNamedQuery<ENTITY_TYPE extends Serializable, RETURNED_CONTAINER extends Collection<ENTITY_TYPE>> extends Command { RETURNED_CONTAINER executeNamedQuery(String namedQuery); } 

Answer 1

I am starting to disagree with the one-character agreement, after its use from the mid-1990s.

I find the readable names more readable. This is useful for understanding both the implementation and the interface of common types.

The ambiguity problem seems overstated for Java. Few class names are all uppercase. Constants are not used in the same context as class names.

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

For example, compare:

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

at

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

Although single-character names have been recommended as a Sun / Oracle convention, conventions are subject to change. The consequences of contesting this convention are insignificant. If you and your team prefer meaningful names for your type parameters, I will personally go after him.

Edit (2015)

The Google style for Java allows you to use either single-letter names or multi-character class names ending in T.

5.2.8 Enter variable type names

Each type variable is specified in one of two styles:

• Single uppercase letter, optionally followed by a single digit (e.g. E, T, X, T2)

• The name in the form used for classes (see section 5.2.2, “Class Names”), followed by the capital letter T (examples: RequestT, FooBarT).

Answer 2

I wonder if I can (should) break the java naming convention for this:

No, this should be avoided, as it becomes easier to confuse type parameters with constants and other identifiers.

Here is a quote from the official generics trail :

Type Naming Conventions

By convention, enter the parameter names in single, capital letters . This contrasts sharply with the conditional naming conventions that you already know about, and with good reason: without this convention, it would be difficult to distinguish between a type variable and a regular class or interface name .

The most commonly used type parameter names are:

• E - Element (widely used by the Java collection structure)
• K is the key
• N - Number
• T - Type
• V - Value
• S , U , V , etc. - 2nd, 3rd, 4th types

You will see that these names are used throughout the Java SE API and the rest of this guide.

Answer 3

Using TDescription is quite common in C #. It supports the name T, but is also descriptive at the same time:

 public interface FindByNamedQuery< TEntityType extends Serialiazble, TReturnedContainer extends Collections<TEntityType>> extends Command { TReturnedContainer executeNamedQuery(String namedQuery); } 

As others have said, ALL_CAPS almost always indicates a constant.

IMO, "it would be difficult to distinguish between a type variable and the usual name of a class or interface. It does not apply here because the prefix T easily identifies it as a type variable.

Again, this is C #, but see MSDN: naming conventions for shared files

In all other cases, the official Microsoft Guidelines for General Naming Conventions:

• Specify general type parameters with descriptive names if only one letter name completely by itself has an explanatory and descriptive name does not add value.

   public interface ISessionChannel<TSession> {...} public delegate TOutput Converter<TInput,TOutput>(TInput from); 

• Consider the constraints on the type parameter in the parameter name. For example, a parameter limited to ISession might be called TSession.

Answer 4

The compiler may not complain, but your teammates may not appreciate that you are using what looks constant in the place where they expect a type parameter.

Answer 5

I think this is a problem for many people using generics. I do not quite agree with Sun's statement that if you use a full-fledged name, it will be confused with the existing class name or something else. In this case, we can start the placeholder name with the dollar as follows:

 public class HashMap<$Key,$Value> implements Map<$Key,$Value>{} 

No one in their right mind calls a class starting with a dollar sign. The dollar sign is also used to indicate the placeholder of many speed patterns for languages, locations, spring, etc. I think this is the way to go.

I have more details about this and reasoning that you do not need to use one letter notation in my blog post if anyone is interested.

http://readsethu.wordpress.com/2012/05/23/a-generic-class-and-why-is-it-confusing/

Answer 6

Like Allen before , my advice comes more from C # (which I have been using widely since 5 months) than Java (with which I played, but it never went very far ...), but I find Java and C # code very similar in spirit (that is, when compared, say, with C ++)

Anyway, when using C # / Java generic (or the C ++ template) on a simple type, I usually use T:

 // C++ template<typename T> class MyClass { /* ... */ } ; // C# public MyClass<T> { /* etc. */ } // Java public MyClass<T> { /* etc. */ } 

Typically, type T comes with a class, so there is no need to describe it anymore.

But when a really descriptive type adds clarity to the code, I do it.

Or when I have two or more types in the same generic / template declaration, this helps to make the difference between the two types. For example (real life example in C #):

 // C++ template<typename T_Data, typename T_Underlying> class MyClass { /* ... */ } ; // C# public MyClass<T_Data, T_Underlying> { /* etc. */ } // Java public MyClass<T_Data, T_Underlying> { /* etc. */ } 

Thus, it is easy to make a difference between the two names in the code, where T and U , well ... kinda anonymous: for those who use Visual C ++, there is debugging inside the Dinkumware STL code, full T , _U , and other one-letter types Names can be quite annoying ... I think this applies to C # or Java code.

You will notice that in each case (C ++, Java or C #) I do not comply with the agreement somewhere in team applications: The reason is that sometimes you just need to try something else instead of following the herd , even if, in the end, you find yourself wrong.

In this case, violation of the naming convention is not critical (Java has worse problems than this petty crime), and finally, you will find out personally and for sure WHY this is wrong, instead of quoting old documents.

And if you find in the end, you're right, well ...

Answer 7

I would name type variables similar to types in a camel shell, but with the prefix "_".

 public interface FindByNamedQuery <_EntityType extends Serialiazble, _ReturnedContainer extends Collections<_EntityType>> extends Command { _ReturnedContainer executeNamedQuery(String namedQuery); }