On Tue, Sep 8, 2009 at 23:35, Stephen C. Gilardi<squee...@mac.com> wrote:
>
> On Sep 8, 2009, at 2:14 AM, Timothy Pratley wrote:
>
>> According to the docstring compare returns -1, 0 or 1:
>> user=> (compare \b \g)
>> -5
>
> We could fix the doc along the lines of:
>
> "Comparator. Returns a negative number, zero, or a positive number when x is
> logically 'less than', 'equal to', or 'greater than' y. Same as Java
> x.compareTo(y) except it also works for nil, and compares numbers and
> collections in a type-independent manner. x must implement Comparable"
>
> or fix the implementation to conform to the current doc.
>
> My current thought is that we should fix the implementation and make a minor
> mod to the doc to replace "Same as" with something like "Works like" because
> compareTo only guarantees the sign of the return value.
>
> Other thoughts?
I'd like to see the behavior of Java's built-in compareTo() followed
and documented as such. This makes implementing compare by calling
.compareTo when appropriate glueless. Also not promising that the
result will be in teh set #{-1,0,1} has two other effects:
1) the implementation gains some freedom, which is occasionally useful.
2) the code pattern that naturally results from this:
"a.compareTo(b) REL 0" is equivalent to "a REL b" where REL is one of
#{ ==, !=, <, >, <=, >=}. Note how following this convention makes
calls to compareTo easy to read because the programmer's intent is
documented by REL and the relative order of a and b, which stays
constant when mentally rewriting the expression.
Yes, this is just as possible when compareTo() promises #{-1, 0, 1},
but such a promise does not lead the caller as inexorably to this
solution, instead you end up with stupidities like this:
[QUOTE source=Robert C. Martin, _Clean Code_, pg57]
[...] In general it is better to find a way to make that argument or
return value clear in its own right; but when its part of the standard
library, or in code that you can not alter, then a helpful clarifying
comment can be useful.
public void testCompareTo() throws Exception
{
[...]
assertTrue(a.compareTo(b) == -1); // a < b
[...]
assertTrue(b.compareTo(a) == 1); // b > a
[...]
}
[/QUOTE]
There are two problems with this code:
(1) It's wrong. It's in violation of the actual contract of
compareTo(), which only promises negative, positive or zero.
(2) If it had been written to the *actual* behavior of the API, the
expanatory comments, which this section is intended to demonstrate the
usefulness of become redundant:
assertTrue(a.compareTo(b) < 0);
assertTrue(b.compareTo(a) > 0);
So, I guess the point of this diatribe is: please follow the behavior
of Java's compareTo, and document this fact in (compare).
// Ben
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
-~----------~----~----~----~------~----~------~--~---
