[gecode-users] Some Feedback on GecodeJ

[andrew cooke]

Hi,

I've been trying out GecodeJ and have a few suggestions.  To set this in
context, I am a software engineer.  I don't have any CompSci related
qualification, but I earn a living programming in Java.  And these
comments are mainly related to making this software easier to use by
people like me (so it's all about conventions and accessibility).


First, doxygen is cool, but Javadoc is the standard.  The first thing I
(or any other engineer) does when assessing a package is look at the
JavaDocs.  I've looked at hundreds, maybe thousands of them.  It's got to
the point where my subconscious expects that format; where I can get an
immediate intuitive grasp of the system by clicking around without (much)
conscious thought.  You broke that.

And if I try to generate Javadoc myself I get a pile of doxygen markup
junk in the text.

I'm serious here.  You might think it's a silly point, but this is a basic
user interface issue.  By using doxygen rather than javadoc you're doing
the equivalent of making a web page with Flash - looks great, but noone
can use it without pain.

And it's not just my subconscious.  When I start writing code in Eclipse
(or IntelliJ), and use the IDE context-sensitive help, I see the doxygen
markup again.  Why couldn't you have used HTML (which the IDEs can
handle)?  Sure some of the maths might look a little less pretty, but it
would be one heck more usable.

Again, this makes things less usable.  You may be cool dudes that use
Emacs, but you're in a tiny minority (heck, when I switched, years ago, I
was in a minority even then).


OK, end of Javadoc rant.  A couple more things.

- Static import functions scare the cattle.  Sure, you want FP in Java and
using static imports are like functions (woot).  But Java isn't FP and
you're going to confuse old folks (you threw me).  Especially when the
majority of the calls (I'm talking about calling Gecode.* methods from
within a Space) take a first argument of "this" (have you made a wrong
term somewhere and ended up in Python land?!).  Why aren't these methods
in some subclass of Space?

- You provide Iterator<> access to search results (neat), but I can't see
an Iterable<> (I may have missed this).  In general, prefer Iterable<> to
Iterator<> where possible (despite the extra work on your part) because it
fits in better with the "for ( : )" syntax:
  for (Foo foo: foos) { ...foo... }
rather than
  while (foos.hasNext()) { ...foos.next()... }

- There seems to be something a bit odd with requiring a copy constructor
in subclasses of Space.  Couldn't you make the type be something like
Space<C extends Space<C>> and then have an abstract method that returns C?
 (called clone or copy or whatever you haven't already used).  Having a
(poorly documented - by defn, since there are no Javadocs...) constructor
convention that uses ideas from C++ ("copy constructor" is not a Java
idiom) isn't a great idea.

Apologies if I've missed something that explains any of the above - I'm
still very much feeling my way around.


OK, that's all.

This looks like a really cool package.  Thanks for providing it.  Oh, also
- some better documentation would help (if nothing else, pointing people
to the excellent chapter 2 of Christian Schulte's thesis would help)!

I guess this looks like one big moan, but this is a really useful piece of
software and I am only trying to suggest things that might help make it
more popular...

Cheers + thanks again,
Andrew