Library for providing calculations in Java

I'm working on a library which will provide easier writing and calculations in Java using a fluent API. This is the library I have implemented with basic functionalities and am now working to improve the API.

I followed instructions given by this but I still have some doubts in naming some classes and methods.

I have several questions oriented on naming those:

-
For calculations, there is the basic class Calculator. For executing calculations, there is the method calculate(). Which is more preferable name: calculate() or simplified calc()?

-
The Calculator class has the ability to track each step of a calculation.

For now I have these methods:

• setTrackSteps(boolean), which enable tracking each step of calculation.

• getTrackedSteps() - return list of each step in TrackedStep object.

• hasTrackedStep - check is tracking calculation steps is enabled/disabled.

Does somebody have some better suggestions for those names?

-
Calculator.getTrackedSteps() return list of object TrackedStep. TrackedSteps is little harsh name. Is there a better name for this?

-
I have separated public API with internal implementations into an internal package. In this package, I have a 'Utils' class with static methods and I'm trying to avoid this generic name. Would HelperUtils be a good name?

I'm trying to avoid prefixes with Calc() or Calculator(), because when the end user uses some IDE and when it start writing Cal, the IDE will provide several classes which start with Cal, including 'Calc..Utils'

If somebody has some other suggestions, the API is available on GitHub.

The class which is related to question 1, 2 and 3:

```
package org.jdice.calc;

import java.text.ParseException;
import java.util.Iterator;
import java.util.LinkedList;

import org.jdice.calc.internal.BindExtensionProvider;
import org.jdice.calc.internal.Bracket;
import org.jdice.calc.internal.CList;
import org.jdice.calc.internal.CListListener;
import org.jdice.calc.interna

For your specific questions:


For calculation there is basic class Calculator and for execute calculation, there is method calculate().


Which is more preferable name calculate() or simplified calc() ?

I'm cool with either, as long as it's applied somewhat consistently. If you don't use calculate and calc in different contexts and implying different meanings, either one's fine.


For now I have those methods:

• setTrackSteps(boolean), which enable tracking each step of calculation.

• getTrackedSteps() - return list of each step in TrackedStep object.

• hasTrackedStep - check is tracking calculation steps is enabled/disabled.

If you have setTrackSteps, consider mirroring with isTrackSteps or getTrackSteps, just to follow JavaBeans conventions.


Calculator.getTrackedSteps() return list of object TrackedStep.
TrackedSteps is little harsh name. Is there a better name for this?

Maybe 'trace' is the word you're looking for?

boolean isTracingSteps()
void setTracingSteps(boolean)
List getTracedSteps()

I have separated Public API with internal implementations into internal package. In this package, I have 'Utils' class with static methods and I'm trying to avoid this generic name.

I don't really see an issue with having a generic name for a generic class. If your calculator class would've been called Utils, or your utility class Calculator, that would be an issue, but basically a namespace for utility methods? Utils is fine.

That said, about that Utils:

-
Utils.equals could be left out and traded for java.util.Objects.equals, provided you can require Java 7 or up.

-
Num[] toNums(Object[]) relies on Num.toNum(Object); maybe put it with Num as well?

-
extractNumber -> divert this through NumberFormat? Perhaps a protected method in your Calculator class, if it's not used outside of it?

More general comments

Self-typing through generics only works for subclasses one level in. I've tried serious wizardry with generics, and never found a good, reliable way to assure the compiler it would get an instance of the current type without having to override those methods manually.

val instead of append? These methods have different names, but they appear to do the same thing: append something. Is there a reason you chose different names for them?

extractNumber is too liberal in what it accepts. It feels a bit odd that I could write:


"Alfred, we're at 800mBar; add 25 cups of sugar and get me 2 cans of shark repellant."

...and end up with 800252. I'd expect the method to throw a NumberFormatException, and possibly shake its head at me for misquoting Batman.

Utils.equals can be briefer. You're taking some responsibilities out of the hands of Object.equals, which is not necessarily a good thing. If you can't go to Java 7 or import the excellent Guava library, you can copy their implementation:

return (a == b) || (a != null && a.equals(b)); // JDK, Guava

StackExchange Code Review Q#48931, answer score: 2