[gecode-users] Some Feedback on GecodeJ

[Ujhelyi Zoltan]

Hi,

I would like to say, that the problems stated in this letter might be  
valid - the Gecode/J code is not too Java-like.

In our Gecode project one of our first ideas was to create some  
wrappers and hide the static code, and provide Javadoc...

We were thinking about it how would it be good to do a possible  
rewrite - but we didn't have any time for that.

But I think, these critics are absolutely valid, and would help a lot  
for the Java port. And I join Andrew by saying, that Gecode is even  
with these small problems a very nice program, but it would help for  
users with Java knowledge if some of these ideas could be addressed.

Thank you for your work,
Zoltán Ujhelyi
On 2008.09.14., at 18:27, andrew cooke wrote:

> 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
>
>
> _______________________________________________
> Gecode users mailing list
> users at gecode.org
> https://www.gecode.org/mailman/listinfo/gecode-users