RFR : CR8004015 : Add parent interfaces and default methods to basic functional interfaces

[Stephen Colebourne]

On 17 December 2012 04:18, David Holmes <david.holmes at oracle.com> wrote:
> On 15/12/2012 4:58 AM, Mike Duigou wrote:
>> On Dec 13 2012, at 22:28 , David Holmes wrote:
>>
>>>> I have added @throws NPE for a number of the default methods. We won't
>>>> be including @throws NPE in all cases where null is disallowed because when
>>>> the @throws NPE is declared the API is required to throw NPE in that
>>>> circumstance. So for cases where the NPE is "naturally" thrown or that
>>>> aren't performance sensitive we will likely add @throws NPE declarations but
>>>> for performance sensitive methods we won't be adding explicit null checks to
>>>> match a @throws NPE specification. There's a tradeoff here in some cases.
>>>> Please feel free to quibble about specific cases as they occur. :-)
>>>
>>>
>>> That doesn't make sense to me. The throwing of the NPE is intended to be
>>> part of the specification not an implementation choice. Further @param foo
>>> non-null, is just as binding on implementations as @throws NPE if foo is
>>> null. ???
>>
>>
>> An "@param foo non-null" by itself is not considered normative because it
>> doesn't document what happens when null is passed. So it ends up being
>> advisory only. An "@throws NPE" is considered normative and the
>> implementation must throw in all circumstances described.
>
>
> Aside: that is an interesting interpretation but from whence does it come?
> It is non-normative by definition because it is incomplete? Or is it just
> non-normative because it is an @param tag?
>
>
>> (Please bear with the step-by-step nature of the following sample, it's
>> incremental pace is not meant to be insulting--it's a write-up for a general
>> FAQ). If I have a method:
>
>
> But once you add the @throws the advisory of the @param is redundant. Hence
> to me it is an either/or situation. Further the advisory, being advisory, is
> useless in my opinion, so not something to use regardless.

Mike, I think your write up makes sense. I prefer the @throws NPE to
be decalared at package or class level with reference to the use of
the "must not be null" or "not null" wording. (whereas specifying all
null-behaviour at the package level is something I dislike).

David, Part of the issue with only specifying @throws is
multi-parameter methods:

/**
 * @param a  sdhgsjgv, not null
 * @param b  sdhgsjgv, null treated as blank string
 * @param c  sdhgsjgv, null ignored
 * @param d  sdhgsjgv, not null
 */
void process(String a, String b, String c, String d) { ... }

Here, there are a combination of possibilities for behaviour. An
@throws would have to reference parameters a and d by name, and would
specify nothing about b or c, thus b and c would still need specifying
somewhere else, most obviously the @param.

Referencing a and d by name is also far harder for tooling to find
(yes I'm aware of the 305/308 annotations but they don't seem to be
being used). Looking for a specific "not null" or "must not be null"
string is easy for other languages to scan for (ie
Fantom/Kotlin/Ceylon).

In other words, in the bigger picture of a general coding standard, I
think the example above is far more consistent and understandable.

Stephen