Two comments on the Constants API

[mark.reinhold at oracle.com]

2018/6/4 10:28:56 -0700, brian.goetz at oracle.com:
> ...
> 
> So, here's two ways we could reduce this friction.
> 
> 1. Drop Constable (but not CD) off of String and friends (the cost of 
> this is a manageable amount of additional spec+compiler complexity). 
> Now the task reduces to explaining String <: CD. Some work on the spec 
> of ConstantDesc, rewriting it from the perspective of "You probably got 
> here because our mutual friend String gave you a coupon for a free 
> symbolic reference", aiming to minimize the amount of time spent in that 
> cognitive-friction zone between "WTF" and resumption of blissful 
> ignorance, could help. And, CD is not _that_ hard to explain; it's 
> something low-level code can use as the description for a low-level 
> component of a classfile.
> 
> 2. Reintroduce some form of ConstantDesc.OfSelf, say NativeConstant 
> (shed to be painted), which implements both CD and Constable and 
> implements its methods. This is trivial to do, and the Javadoc for this 
> can be much simpler and friendlier than the Javadoc for CD, since it can 
> appeal to "I'm just a convenient supertype for String and four special 
> Number types." The time spent in the cognitive-friction zone is even 
> less. But, its not perfect; while now String only directly extends 
> NativeConstant, CD and Constable will still show up in the list of "all 
> implemented interfaces." This could still be confusing.
> 
> Its possible that the downside of (2) could be further mitigated by 
> Javadoc presentation changes (such as, in the "all implemented 
> interfaces" list, instead of saying "A, B, C", it could say "A, B (via 
> A), C", to make it clear what the inheritance path was. If this list 
> for String said "All implemented interfaces: Serializable, 
> Comparable<String>, CharSequence, NativeConstant, ConstantDesc (via 
> NativeConstant), Constable (via NativeConstant)", it would be clear that 
> the weirdnesses are introduced by NC, and a short trip to the NC docs 
> says "nothing to see here, move along." In other words, maybe this is 
> mostly a tooling problem. (Or maybe this just is creating new problems.)
> 
> We've been in (2) before and I'm fine to go there again; the thing to 
> most like about (2) is that it creates a type that explains the role of 
> these five special types at a higher level. (1) has the advantage of 
> reducing the number of weird types that show up, but only gets us 
> halfway back to blissful ignorance (there are only three numbers in 
> computer science; 0, 1, and n. We're in n now, this gets us back to 1, 
> hence, halfway.)

Of these two options, I’d go with (2).  A `NativeConstant` interface
(or whatever it turns out to be named) is much easier to explain than
`ConstantDesc` since it conveys a meaning that can make sense to
non-experts (and offhand I don’t see how to give `ConstantDesc` itself
such a name).

I agree that a small change to how Javadoc presents lists of implemented
interfaces could mitigate the downside of this option, but I’ll resist
approaching that bikeshed here.  (Personally I usually don’t read the
“All Implemented Interfaces” list unless I really need to, but maybe
that’s just me.)

- Mark