Xith3D goals

[William Denniss]

Here is a list of goals that I would like to work towards.

• Remove unimplemented never-to-be-implemented methods and fields.
  
• Create list of "Core" packages and mark them as so in package level javadocs.  Non-core and experimental packages should also be marked as such.
  
• Fully javadoc the Core packages and mandate that future changes must be documented as well
  
• When OS X LWJGL support exists, promote the LWJGL renderer to an officially supported renderer aiming at 100% compatability for the Core packages with the JOGL renderer.
  

Yuri has also mentioned some features which would be very nice (ViewPlatform, sterio viewing, shaders, render to texture etc...).

What do people think?  Are there any objections to removing those useless methods and fields?  I understand that some fields were added for Java3d compatability (even though they do nothing in Xith3d).  Any reason to keep them now?

Will.

[ap_kelly]

I've not used the Xith3D packages yet, but I wouldn't remove any methods and attributes just yet. I'd simply mark them as depricated (if they're not already).

I come from a pure OO world so the idea of exposed attributes without getters and setters worries me; I don't think you can deprecate a field!

Regards,

Andy.

[William Denniss]

deprecating is an option but rather pointless if nobody uses them anyway.  The methods I speak of are unimplemented (i.e. {});

By "fields" I meant constant fields, i.e. http://xith.org/javadoc/constant-values.html#com.xith3d.scenegraph.TransformGroup.LAST_CAPS_BIT_POSITION

These constant fields and methods are ghosts and existed for Java3D compatibility.  I am testing the water to see if anyone is actually using them or can see a current need for them.  I see more people getting confused ("I was calling this method and don't know why nothing was happening").

Xith3D does follow OO principles.

Will.

Games published by our own members! Check 'em out!

[SpuTTer]

I +1 removing everything that is non-implemented. Add it to a todo list or something if it will eventually be added, but for now I think it just causes confusion.

[kevglass]

This is a very good idea. +1. If removing an empty method breaks someone's code they can of course simply remove the call since it didn't do anything anyway.

You'd be pushed to implement setters for the fields in question by the way since they're constants

Kev

[Jens]

+1 for documenting the core packages. Along with better Javadoc I'd also suggest to introduce official Xith3D code conventions (should be enough to put them in the xith.org docs section). Basically we can adopt the code conventions by Sun and just mention the differences (if any).

[kevglass]

While I totally agree that specifing exceptions in documentation is a good idea I can't find any reference to it being a convention endorsed my the Sun Conventions?

I'd really like to find the bit since I could use it to club co-workers into fully documenting their methods..

Kev

[William Denniss]

sounds fine to me -- Sun conventions + exceptions documented.

Eclipse has the lovely Source->Format option which can do everything for us, but it does make it a bit harder to compare one version of Xith3D to another depending on how many formatting changes this would make.

Will.

[Jens]

Eclipse has the lovely Source->Format option which can do everything for us, but it does make it a bit harder to compare one version of Xith3D to another depending on how many formatting changes this would make.

I like the Source->Format option. Source -> Add Javadoc Comment is useful, too. Eclipse also has the advantage that the code conventions can be saved in an xml-file. Version comparing can get a bit more difficult, but as the format will only change once per file (depending how much the files differ from the conventions) it isn't such a big problem and makes the code more readable.

I suggest taking the following simple steps:

• create a simple "(not yet) official code conventions" page at xith.org
  
• write a paragraph in the xith.org docs section linking to this new page
  
• create a new thread in this forum where everyone can write down suggestions for exceptions from the Sun code conventions (or more detailed explanations if necessary)
  
• after a fixed time span without new suggestions the code conventions become official
  

Of couse it would also be nice, if people can download code convention files for eclipse (or other IDEs), when they start to differ from Sun conventions for which eclipse has built-in support. Are you happy with this procedure?

[William Denniss]

• create a new thread in this forum where everyone can write down suggestions for exceptions from the Sun code conventions (or more detailed explanations if necessary)
  

done

Will.

Games published by our own members! Check 'em out!

[William Denniss]

I have now removed most of the unimplemented methods from com.xith3d.scenegraph.

CVS log/diff here:
https://xith3d.dev.java.net/servlets/ReadMsg?list=cvs&msgNo=412

It is certainly much cleaner now they are gone - less chance of error, and less need to look at the source just to see if a method is implemented or not.

If you were inadvertently using one - you may need to comment it out in your code for it to compile.  Interestingly there was one such call in com.xith3d.io - and one call in Odejava (no wounder that code wasn't working!).

Will.

[Jens]

Added paragraph to xith.org docs section and edited code conventions page. (I like the Wiki. )

[William Denniss]

The biggest problem with changing the code formatting is that it renders any patches we recieve against the un-formatted version useless (or at least a real pain).  We should take a gradual approach and give people plenty of notice if this is going to go ahead.  Certainly mandating that all new code adher to the standard is a good idea.  This shouldn't really be a burden on developers, as far as I know most IDE's do the formatting for you as you go.

Will.

[William Denniss]

I've now committed a patch to remove most unused constants from the com.xith3d.scenegraph package.  Most had to do with capacity bits, a concept which Xith3D hasn't really implemented (except some in geometry arrays which I did not remove).  This is not to say that capacities are bad - in fact they are very good.  Having a compile feature to collapse unneeded TransformGroups etc would be very good.  Until the time however when this support is added in, these constants only serve to confuse and give the impression that it is supported when indeed it isn't.

The javadocs are becoming a bit more usable now.  All we need are some more comments and we'll be right.
Compare http://xith.org/javadoc/constant-values.html to http://xith.org/javadoc/constant-values2.html  the former only has used constants where as the latter has all the old unused ones as well - needless clutter.

CVS log/diff here: https://xith3d.dev.java.net/servlets/ReadMsg?list=cvs&msgNo=413

I have now removed just about all unused methods and constants from com.xith3d.scenegraph.  I believe this is a step in the right direction to make programming with Xith3D referencing only the javadocs (and not the source) possible.  If you see a method in the javadoc or your IDE autocomplete, you can be 99% sure it isn't a phantom method.

Will.

[Bombadil]

Do you think you could also remove all the references to the log4j package which isn't used anyway?
To run Xit3d the logj4 jar isn't needed, just to compile it. So I usually tend to remove them from hand...

[William Denniss]

Log4j is a very powerful (and tiny) library.  I think it would even be better to go the other way and convert Xith3D's log statements to use log4j more.

Will.