Why prefer a wildcard to a type discriminator in a Java API (Re: Effective Java)

Question

In the generics section of Bloch's Effective Java (which handily is the "free" chapter available to all: http://java.sun.com/docs/books/effective/generics.pdf), he says:

If a type parameter appears only once in a method declaration, replace it with a wildcard.

(See page 31-33 of that pdf)

The signature in question is:

public static void swap(List<?> list, int i, int j)

vs

public static void swap(List<E> list, int i, int j)

And then proceeds to use a static private "helper" function with an actual type parameter to perform the work. The helper function signature is EXACTLY that of the second option.

Why is the wildcard preferable, since you need to NOT use a wildcard to get the work done anyway? I understand that in this case since he's modifying the List and you can't add to a collection with an unbounded wildcard, so why use it at all?

Answer 1

Why is the wildcard preferable

I believe Josh states it clearly:

In a public API, the [wildcard] is better because it’s simpler.

That is, for the users of the API. The small extra complexity in the implementation is not visible from outside. And as the implementation is written only once, but the API may be used many times by many different people, simplifying the API at the cost of making the implementation slightly more complex is still an overall win.

> why use it at all?

You mean, why is it better than

public static void swap(List list, int i, int j)

? Because the latter would forfeit generics altogether, letting the compiler omit all generic type checking, and allowing us to write sloppy code. I think it is better to use generic type signatures even if they are this general, just to keep up the habit.

Update reflecting on the comment below

You forgot the generic parameter declaration from the second signature, correctly it should be

public static <E> void swap(List<E> list, int i, int j)

That is, <E> appears twice, for no added benefit, vs <?> appearing only once in the first signature. This is why it is simpler.