Re: [eclipse-dev] The ongoing migration saga

["Bob Foster" <bob@xxxxxxxxxxxx>]

I see you have been asked already, "What standard practice?" So I'll just
ask, "What spec?"

Bob

----- Original Message ----- 
From: "Jim des Rivieres" <Jim_des_Rivieres@xxxxxxxxxx>
To: <eclipse-dev@xxxxxxxxxxx>
Sent: Thursday, December 11, 2003 12:41 PM
Subject: Re: [eclipse-dev] The ongoing migration saga


> > I have previously noted that the Eclipse API is rather notorious for
> > seldom documenting when null arguments are or are not accepted.
>
> The Eclipse API follows the standard Java practice of explicitly
> specifying where null is allowed for all API method parameters, return
> results, and field (and also elements of arrays or collections). If the
> spec does not *explicitly* state that null is allowed, it is *never*
> allowed. The results of passing null are generally left unspecified
> (implementation might throw some kind of runtime exception, or might not).
>
> In the particular case you mention of TreeViewer.Reveal, the spec does not
> allow the element to be null. In the course of fixing a viewer related bug
> (https://bugs.eclipse.org/bugs/show_bug.cgi?id=45253) caused by null being
> passed, the implementation was changed to include an up-front null check.
> This appears to have caught your code, which was passing null and counting
> on it to be ignored.
>
> The implementation of the API method should have been rejected null
> parameters all along, so that client code could not accidentally get away
> replying on more than is promised.
>
> ---jim
>
>
>
>
>
> "Bob Foster" <bob@xxxxxxxxxxxx>
> Sent by: eclipse-dev-admin@xxxxxxxxxxx
> 12/11/2003 12:45 PM
> Please respond to eclipse-dev
>
>
>         To:     <eclipse-dev@xxxxxxxxxxx>
>         cc:
>         Subject:        [eclipse-dev] The ongoing migration saga
>
>
>
> Now that I have a version that "works" with M5 a couple of users have
> reported bugs that look very much like API that was previously accepting
> null arguments is no longer. The clearest case of this is in TreeViewer
> reveal(), which I was clearly calling in prior releases with null and now
> runs afoul of an assertion.
>
> I have previously noted that the Eclipse API is rather notorious for
> seldom
> documenting when null arguments are or are not accepted. This forces the
> user to read the code to discover the allowed argument range, and then of
> course when the code changes later it may be claimed that the caller is
> depending on "internal details". I'd like to head this off in the general
> case by asking, what the heck else _could_ one depend on, with
> documentation
> like:
>
> @param element the element
>
> In this particular case, reveal() was clearly coded to accept null in 2.1.
> Adding the assertion changed the API, actually worse than changing
> argument
> types because it is not detected by the compiler.
>
> Not to pick on this one little change; if it is an outlier I apologize to
> the developer involved. But there is a lot of code getting "cleaned up" at
> the moment, and I'm betting if there is one case there are a hundred.
> Could
> Eclipse please supply, as part of your migration docs, a list of all cases
> where assertions have been added where there were none before? And how
> about
> updating the javadoc at the same time, so the API finally gets documented?
>
> Thanks.
>
> Bob Foster
>
> _______________________________________________
> eclipse-dev mailing list
> eclipse-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe
> from this list, visit
> http://dev.eclipse.org/mailman/listinfo/eclipse-dev
>
>
>
> _______________________________________________
> eclipse-dev mailing list
> eclipse-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
> http://dev.eclipse.org/mailman/listinfo/eclipse-dev
>
>