Official Definition
From the reference docs of Comparable.compareTo(T):
Compares this object with the
specified object for order. Returns a
negative integer, zero, or a positive
integer as this object is less than,
equal to, or greater than the
specified object.The implementor must ensure
sgn(x.compareTo(y)) ==
-sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must
throw an exception iff y.compareTo(x)
throws an exception.)The implementor must also ensure that
the relation is transitive:
(x.compareTo(y)>0 && y.compareTo(z)>0)
implies x.compareTo(z)>0.Finally, the implementor must ensure
that x.compareTo(y)==0 implies that
sgn(x.compareTo(z)) ==
sgn(y.compareTo(z)), for all z.It is strongly recommended, but not
strictly required that
(x.compareTo(y)==0) == (x.equals(y)).
Generally speaking, any class that
implements the Comparable interface
and violates this condition should
clearly indicate this fact. The
recommended language is “Note: this
class has a natural ordering that is
inconsistent with equals.”In the foregoing description, the
notation sgn(expression) designates
the mathematical signum function,
which is defined to return one of -1,
0, or 1 according to whether the value
of expression is negative, zero or
positive.
My Version
In short:
this.compareTo(that)
returns
- a negative int if this < that
- 0 if this == that
- a positive int if this > that
where the implementation of this method determines the actual semantics of < > and == (I don’t mean == in the sense of java’s object identity operator)
Examples
"abc".compareTo("def")
will yield something smaller than 0 as abc is alphabetically before def.
Integer.valueOf(2).compareTo(Integer.valueOf(1))
will yield something larger than 0 because 2 is larger than 1.
Some additional points
Note: It is good practice for a class that implements Comparable to declare the semantics of it’s compareTo() method in the javadocs.
Note: you should read at least one of the following:
- the Object Ordering section of
the Collection Trail in the Sun Java
Tutorial - Effective Java by
Joshua Bloch, especially item 12:
Consider implementing Comparable - Java Generics and Collections by
Maurice Naftalin, Philip Wadler, chapter 3.1: Comparable
Warning: you should never rely on the return values of compareTo being -1, 0 and 1. You should always test for x < 0, x == 0, x > 0, respectively.