The implementation of default methods

[Doug Lea]

On 12/15/12 01:50, David Holmes wrote:

>>>
>>> 2. Document "The default implementation behaves as if..." (Or whatever
>>> Doug's
>>> proposed wording is.)
>>
>> In j.u.c, we always say "is behaviorally equivalent to" but I dropped
>> the "behaviorally" in Map candidate because someone once told me
>> it was overly pedantic :-)
>>
>>>
>>> 3. Document "The default implementation MUST"
>>
>> Isn't this just the normal spec part, that should precede the default
>> implementation part?
>
> I think not. The "normal spec" describes the abstract operation. "The default
> implementation MUST" specifies the concrete implementation.

Sorry, I don't get it. If you say what the method requires and
then say what default implementation is behaviorally equivalent to
in terms of other methods (or imported functionality),
you should in principle be done.

The equivalence-based wording is critical though, and requires some
hard work (and a little judgement) to get right. AbstractCollection
(and other AbstractX's in j.u) specs include some now-regrettable
wording saying exactly what they do rather than what they are equivalent
to, which has prevented some improvements over the years.

While I'm at it: It is currently a nuisance to get
javadocs right when you override a method defaulted in
AbstractCollection. Usually, no combination of @inheritDoc's
will save you from copy/paste/hack to edit out the default
implementation description while keeping the main spec.
This will probably happen a lot when using defaulted
implementations.

-Doug