Pull to refresh

Apply «capital letters jam» for generic type parameters

Reading time2 min
Views889
Typical type parameter?
Typical type parameter?

There are such types in Java - called "Generics".
And the point here is that there is a convention for naming generic type parameters WITH ONE CAPITAL LETTER.


Generics exist only at the compilation stage and only for the compiler.

So, the problem is that in practice, when you need several type parameters and especially with the same first letters of classes, it breaks down code readability:

  1. It is not clear by one capital letter what type is behind the letter.

  2. You can start "dancing" and add a number to the letter, BUT again - it will not make it readable for developers who will had to support your code.

Let's consider an example. Below is the interface with 4 type parameters. And 2 last types presents different classes, and both of classes are named like "...Param".

What if there were no 2 letters here in type param name??

/**
 * Flow of data mart processor.
 *
 * @param <FT> flow tables type
 * @param <TS> flow task steps type
 * @param <FP> flow param type
 * @param <TP> task param type
 */
public interface Flow<FT extends FlowTables, TS extends TaskStep<FT, FP, TP>, FP, TP> {

    /**
     * Plans a new task in the flow.
     *
     * @return new task
     */
    Task<FT, TS, FP, TP> nextTask();

    /**
     * Plans a new task in the flow.
     *
     * @param name task name
     * @return new task
     */
    Task<FT, TS, FP, TP> nextTask(String name);

    /**
     * Plans a dataset calculation for later using in flow.
     *
     * @param key   the key under which the dataset is stored
     * @param value dataset calculation function
     * @return this flow
     */
    Flow<FT, TS, FP, TP> putToStorage(String key, Function<Param<FT, FP>, Dataset<Row>> value);

    /**
     * Starts flow.
     *
     */
    void start();
}

We will definitely had to give some random one letter to identify needed type. Maybe for someone it is fine, but when:

  1. There are no explaining java docs;

  2. You are new to project;

  3. You have to work with several such "unclear" classes.

Then it becomes serious task to understand what type parameter expected by contract.

Capital letters jam - it is technique of naming type parameter by capital letters of class name.

And yes, in such approach we will definitely violate the known convention, but at least we will be able to understand from the code what kind of type it is, instead of observing the convention and suffering.


When developing classes with one type parameter - is is okay to give one letter to that parameter. But when there are several types and with the same class names - better apply "capital letters jam" technique to make it clear.

If you have what to say about the topic and want to give negative rating - please feel free to write your comments to understand your opinion. Otherwise it is not serious and it is not clear why you vote negatively.

And of course If you like this article, please vote UP - this will support me to write more such posts with real code examples!

Tags:
Hubs:
Total votes 1: ↑0 and ↓1-1
Comments2

Articles