Two comments on the Constants API

[Brian Goetz]

I agree that (2), possibly along with some improvements in Javadoc 
presentation (which can be handled as a separate discussion), would go a 
long way towards avoiding this particular cognitive-friction pothole, 
and its perfectly unintrusive to the use cases for this API.  So, I'm 
good with that.

I think NativeConstant is an OK name; BuiltInConstant might have less 
confusion with uses of "native" as in native methods or JNI or Panama.  
The bikeshed is open...

On 6/4/2018 2:34 PM, mark.reinhold at oracle.com wrote:
> 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