| Re: [e4-dev] API-Design Questions |
> -----------8<-----------
> > /**
> > * Returns a collection of all {@link MInputPart} with the
> inputURI-Attribute set to the given
> > * value
> > *
> > * @param inputUri
> > * the input uri to search for, must not be <code>null</code>
> > * @return list of parts or an empty collection
> > */
> > public Collection<MInputPart> getInputParts(String inputUri);
> -----------8<-----------
>
> As you'll see the method specs that NULL is not an allowed value. Now I
> think we should define what writing methods like this means.
I agree with you (and Francis) that our convention should be to throw an IllegalArgumentException. This is clearer than other exceptions (assertion failed, null pointer) because it puts the blame clearly on the caller, where it belongs.
However, and here I also agree with Francis, the JavaDoc should not make promises about how it handles such cases. Generally, it is better to leave error cases unspecified if the caller can prevent the errors from happening. This would allow us to relax the API contract in the future, or to make performance optimizations such as taking out checks, as needed.
For JFace and the Workbench (and probably other Eclipse APIs), we have relied on an article "How to use the Eclipse API" (http://www.eclipse.org/articles/article.php?file=Article-API-Use/index.html) that was written very early to lay some ground rules. We have since learned that you cannot assume that everybody is going to read documents like this, and that it is better to spell those cases out explicitly in each API method. It's painful to be verbose like that, but it will make it easier to rule out misunderstandings.
Boris