I propose introducing an enum Cmp with values lt, eq, and gt, and to change the return type of sys::Obj.compare to Cmp instead of Int. This suggestion is modeled after Haskell which uses Cmp with values LT, EQ and GT for comparisons.

The method sys::Obj.compare states that methods should return -1, 0 or 1. This is a narrow range on a 64-bit integer, and users migrating from Java are likely to miss this distinction between Fan and Java, which uses <0, 0 or >0 instead to identify the result. So Java has the benefit of using the full integer range so that any integer is a valid result, but with the drawback that you have to do up to two more comparisons (<0 and >0, again!) on that integer just to evaluate the result of the comparison.

By using a Cmp we neatly sidestep the integer range / comparison mismatch.

Actually Fan is just like Java, it is <0 and >0. So I need to update the docs.

I think the question is "why stick with Java's <0,0,>0 convention"?

The downside of that is that it encourages this:

return this.a - other.a

which can overflow and give the wrong answer.

Using an enum would prevent that possibility.

Of course it depends on whether you implement it in bytecode as an implementation of Comparable?

I think -1, 0, 1 is well enough established a convention not to cause confusion. Haskell can get away with a newtype on that because under the covers, it's just an integer by another name. In Fan, enums are heavyweight tanks, implemented as Java classes with full method and field support. To bake them in would require adding magic to the compiler which isn't really called for in this situation.

The downside of that is that it encourages this:
  return this.a - other.a
which can overflow and give the wrong answer.

Does sys::Int.compare guard against this?

There are a number of languages now that use number objects that turn into bignums as soon as they get too big. But not Fan. Doing the checks on each operation is pretty expensive. So, Fan will let you shoot yourself in the foot over this issue, but it provides a 64-bit safety on the trigger. If you ever use a number greater than nine quintillion, you're probably better off using a different representation anyway.