On Thu, Mar 1, 2012 at 2:02 PM, Mike Duigou <mike.dui...@oracle.com> wrote:
I always read @throws declarations as "if thrown then description was the
> cause" rather than "will be thrown if description".
FWIW, I have never read them this way, and I think there are plenty of
examples in the JDK that illustrate that it doesn't seem that way either,
e.g. "@throws NullPointerException if this collection does not accept null
elements and element is null" (paraphrased). With your convention, it
would not have needed to add the "if" part.
A minor difference in interpretation that can sometimes be useful.
>
> For this particular case the restriction on sort() seems to serve only to
> blunt the usefulness of Collections.emptyList and singletonList(). I'd
> prefer to bend the rules slightly rather than requiring developers to use
> empty and singleton ArrayLists.
>
Personally... I don't think this is the right way to think about this.
Lists are either immutable or not (counting partially-mutable lists e.g.
Arrays.asList in the second group), and people just shouldn't be passing an
immutable collection to sort().
The status quo is that the user who actually experiences this problem can,
at worst, replace
Collections.sort(list);
with
if (list.size() > 1)
Collections.sort(list);
... that doesn't seem so bad to me.
Just my $.01 ...
--
Kevin Bourrillion @ Google
Java Core Libraries Team
http://guava-libraries.googlecode.com
