API design guidelines

The following guidelines are meant to make the user experience more pleasant. They are aimed to help the user make use of existing tools and increase productivity. As a first guideline, keep in mind that somebody other than you will use your code.

Object orientation

Object orientation is a design approach that attempts to model real world objects in the code.
Try to think in objects.
Make use of the visibility of objects.
Hide your implementation from the user.
On the other hand, not every class needs to have a set of private data members with a full-blown set of Setters and Getters. It is ok to have a class with only public data members.
Rule: What belongs together logically should be handled together
Example:

Optimization

Optimization obfuscates code. It also forces you to change your intuitive approach.
Rule: First, write your code. Then profile it. Then, if necessary, optimize it.

Status codes

In the good old Fortran and C days, obscure statuscodes and bitfields were common sight. While it is true that your code should be optimized at the persistence level, make sure you include definitions of your statuscodes in the API. The use of EnumSet is encouraged.

good code 

bad code

I would like to share some comments about the API from a user point-of-view.

Status codes

The Java language was awarded such a nice enum class. Is there really a performance issue in using ints for status bits or types ?

/** Type of hit. Mapping of integer types to type names
  * through collection parameters "TrackerHitTypeNames"
  * and "TrackerHitTypeValues".
  */

Examples:

• the FitStatus class
• in FtfTrack.java: if ( getPara().szFitFlag == 1 )
  especially the latter class would benefit from using enums or at least symbolic constants, if the author ever wants to hand over maintenance to someone else.

This does not help me at all when I am coding, and I don't want to have a web browser open all the time to see what the type, status, flag, whatever, actually stands for. This is where I would like to take advantage of Code Completion.

org.lcsim.mc.fast.cluster.ronan

I disagree with the use of names for packages.

JavaDoc

...

"Overloaded Operators"

It is very confusing to have members like add(Object o1, Object o2) as members of the classes. This is counter-intuitive. Either there ought to be a supporter class with static members only, or the member of the type class expects only one argument.
So:
vec1.add(vec1, vec2);
vec1.add(vec2);
import static x.y.add; add(vec1, vec2);

...