Comments and questions are welcome

[m-vokhm]

I will appreciate any comments on the project.
Any questions are welcome.
JavaDoc as separate HTML files and a more informative README are coming soon.

[Algomorph]

The README is very well-written an informative.

I would add also the main motivation for Quadruple: that it's much faster than BigDecimal, which makes it much more useful for resource-intensive scientific computing and simulations.

This could be phrased as a separate paragraph under a separate ##heading and include a chart demonstrating the performance of Quadruple vs. BigDecimal on some common floating-point computing benchmark.

[m-vokhm]

Yes, it's a good idea, thank you. I'll put it among my TODOs for the nearest future. And a very simple usage example, like the square of a circle computation, would be probably helpful too.

[Algomorph]

Are these packages included in Java SE 15 JDK?

import com.sun.istack.internal.NotNull;
import com.sun.istack.internal.Nullable;

In order to get the imports in IntelliJ, I had to do this instead:

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
//import com.sun.istack.internal.NotNull;
//import com.sun.istack.internal.Nullable;

And I had to add the corresponding dependency to Maven:

<dependency>
    <groupId>org.jetbrains</groupId>
    <artifactId>annotations</artifactId>
    <version>RELEASE</version>
    <scope>compile</scope>
</dependency>

1. Perhaps there is a proper dependency to retrieve com.sun.istack.internal?
2. Why isn't pom.xml included in the project if it's using third-party packages? It seems to be a standard thing to include it, e.g. see google-java-format repository.

[m-vokhm]

Are these packages included in Java SE 15 JDK?

import com.sun.istack.internal.NotNull;
import com.sun.istack.internal.Nullable;

They are in SE 1.8 I use for this project.
Never thought they might cause problems.

Now I'll try to learn about their fate in the later versions.

[m-vokhm]

They are not necessary, in fact. I've removed them from the code (have not committed yet)

[Algomorph]

Here is some (quite old) code to test performance against in the future, aside from the BigInteger implementations of various vendors:
https://github.com/tbuktu/bigint

[m-vokhm]

Is it correct to compare an integer arithmetic with a floating-point one? May be you've confused BigInteger with BigDecimal? Or what did you mean?

[Algomorph]

Yes, you are right, my bad. If I find similar examples for BigDecimal, I will post them here.

[Algomorph]

Here is a SO page that discusses the issue of poor BigDecimal performance:
https://stackoverflow.com/q/611732/844728
I see that some people provide alternatives to try in their answers, such as the Apache Commons Math library here. These might be good to benchmark against.

Also, I find that SO is an excellent place to promote your code. You can answer the above question (and similar questions) by posting a link to (and a description of) your library, which can be used as an alternative. However, you have to be careful to make sure you are answering exactly the question that was asked (however old it may be), because of the strict question/answer format of the website.

[m-vokhm]

Yes, and there are some more info there on that topic, e.g. https://stackoverflow.com/questions/277309/java-floating-point-high-precision-library/284588#284588
I do keep it in mind.

[Algomorph]

From the perspective of style, the code looks very good already.

There are a few minor improvements that I think can be made, but I will add more comments as a reply to this thread if I see more issues.

Removing dead code.

1. I'm not sure about this whole dummy() method here. Is it intended to... "sometimes" be used?
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Lines 4992 to 4997 in c8f50a9

   	private static void dummy() { // Just to prevent removing static import of 'say' from imports
   	// 20.10.02 13:18:53 TO DO The imports used for debugging, to be removed after it's finished
   	// say(AuxMethods.hexStr(BUFFER_6x32_A));
   	// say(hexStr_u(BUFFER_6x32_A));
   	// say(hexStr_(BUFFER_6x32_A));
   	} // private static void dummy() { // Just to prevent removing static import of 'say' from imports

2. This one should probably be removed altogether. If it's a way to test code, perhaps it should be restored / revised and moved to testing?
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Lines 3105 to 3118 in c8f50a9

   	/**
   	* 20.10.02 13:16:54 Was used for debugging
   	* @param indent
   	* @param exp2
   	* @param product
   	*/
   	@SuppressWarnings("unused")
   	private static void logExpAndMant(boolean indent, long exp2, long[] product) {
   	// final String prefix = indent? "\t\t\t\t\t\t" : "";
   	// log_(prefix + "exp2:\t" + hexStr((int)exp2));
   	// log("\tmant:\t" + hexStr((int)product[5]) + "\t = \t" + (int)product[5]);
   	// say_("exp2:\t" + hexStr((int)exp2));
   	// say("\tmant:\t" + hexStr((int)product[5]) + "\t = \t" + (int)product[5]);
   	}

3. I'm guessing all extra commented lines like this one were meant to be removed from the POS_POWERS_OF_2 table?

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 1627 in c8f50a9

   // {1, 0x6666_6666_6666_6666L, 0x6666_6666_6666_6666L, 0x6666_6666_6666_6666L},

Removing abbreviations from method & variable names

Abbreviations typically shouldn't be used in method / class / variable names, since they tend to be ambiguous. Moreover, it is harder for the coder to remember which version of an annotation was used than to remember the whole word, e.g. buff or buf? Notable exceptions are "min" and "max", in my opinion, which are acceptable. An outside coder should be able to glean the meaning of a method from its name without having to read through the rest of the code to familiarize him-/herself with the context.

Luckily, refactoring features in Eclipse and IntelliJ are more than sufficient to quickly rectify naming issues.

1. "Mant" and "mant" should be expanded to "Mantissa" and "mantissa", respectively, throughout the code. Examples:
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 234 in c8f50a9

   public Quadruple(boolean negative, int exponent, long mantHi, long mantLo) {

   
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 3508 in c8f50a9

   private long addMant(long mantHi2, long mantLo2) {

2. "Mult" and "mult" should be expanded to "Multiply" and "multiply", respectively, throughout the code. Likewise for "subtr"--> "subtract". Examples:
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 2109 in c8f50a9

   private long[] multMantByMinNormal( long[] product_4x64) {

   
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 4001 in 068dabf

   private Quadruple multUnsigned(Quadruple factor) {

   
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 3974 in 068dabf

   private long subtrMant(long minuendHi, long minuendLo, long borrow) {

3. "Buf"/ "Buff" and "Buffs" should be replaced by "Buffer" and "Buffers", respectively. Examples:
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 4938 in 068dabf

   private static void multBufByDigit(long[] buff, long digit) {

   
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Line 4926 in 068dabf

   private static int compareBuffs64(long[] buff1, long[] buff2) {

NB: These are only some examples I found. If you find more abbreviations (except "min" and "max"), they should probably be changed to full words as well.

#### The first sentence of each method's block comment should use imperative mood
I changed my mind about this. See comment at the bottom.

For instance, this comment:

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Lines 4920 to 4921 in 068dabf

	/** Compares two numbers
	* represented as arrays of {@code long} (big-endian, most significant bits in buff[0])

Would be changed to:

  /** Compare two numbers
   * represented as arrays of {@code long} (big-endian, most significant bits in buff[0])

This is a tricky issue: it is among the newer standards to be adapted, and a lot of old (and good) code out there uses alternative strategies. However, it is something to consider. Here is more information on the topic: https://stackoverflow.com/a/61624638/844728

[EDIT] Java API seems to use the indicative mood, which is what you have. I suppose it is better to stay consistent, so I withdraw the above proposal about imperative mood.

[Algomorph]

It looks like you diligenlty added the method signature after the closing brace of each method, e.g.

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Line 1061 in 068dabf

} // public static Quadruple add(Quadruple op1, Quadruple op2) {

This approach is reasonable in certain cases, e.g. large C++ namespaces, as it allows for the coder to keep track of the context when the beginning of the namespace is not visible.

However, in cases where indentation can used to keep track of methods, and the methods themselves are not very long, I feel that this approach is not justified. The major disadvantage is that not all IDEs are capable of refactoring of method names within comments (and the ones that are still impose an overhead of manual oversight for such cases). Hence having these comments will either increase maintenance time (with the maintainer being forced to update the comments after refactoring the method names) or make those closing comments misleading (if they are allowed to be outdated).

[Algomorph]

P.S. on the topic of abbreviations NaN is a reasonable, unambiguous acronym and should be allowed to remain the way you have it. Acronyms are different from abbreviations, common ones can and should be used in method/class/variable names. However, "exp" and "EXP" should probably be changed to "exponent" and "EXPONENT".

[Algomorph]

Brace style

It is considered good style to always enclose the body of an if, else, or for statement (and others) in curly braces, even when the body consists of a single line. This allows to decrease maintenance time and reduce potential errors when more lines are added to the body in the future. It also increases readability of the code.

Example:

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Lines 4059 to 4060 in 068dabf

	if (productExponent < -129) // Product would be less than (MIN_VALUE / 2)
	return productExponent;

The above should be changed to:

      if (productExponent < -129)  // Product would be less than (MIN_VALUE / 2){
        return productExponent;
      }

More example occurrences in the current code:

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Lines 4134 to 4135 in 068dabf

	if (productExponent <= EXP_MAX)
	shiftBufferRight(product, isRoundedUp);

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Lines 4174 to 4177 in 068dabf

	if (isRoundedUp)
	shiftBuffRightWithoutRounding(buffer);
	else
	shiftBuffRightWithRounding(buffer); // There can't be carry to the highest (implied) bit, no need to check it

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Lines 4204 to 4205 in 068dabf

	for (int i = 5; i >= 2; i--)
	buffer[i] = (buffer[i] >>> 1) | (buffer[i - 1] & 1) << 31;

[m-vokhm]

Removing dead code.

1. I'm not sure about this whole dummy() method here. Is it intended to... "sometimes" be used?
   

   Quadruple/src/com/mvohm/quadruple/Quadruple.java

   Lines 4992 to 4997 in c8f50a9

   	private static void dummy() { // Just to prevent removing static import of 'say' from imports
   	// 20.10.02 13:18:53 TO DO The imports used for debugging, to be removed after it's finished
   	// say(AuxMethods.hexStr(BUFFER_6x32_A));
   	// say(hexStr_u(BUFFER_6x32_A));
   	// say(hexStr_(BUFFER_6x32_A));
   	} // private static void dummy() { // Just to prevent removing static import of 'say' from imports

Yes. There is a slight suspicion that this may still be useful if a bug shows, so I would prefer not to remove it for a while, so as not to remember later. I'll remove it when the confidence grows a little more.

[m-vokhm]

It looks like you diligenlty added the method signature after the closing brace of each method, e.g.

Quadruple/src/com/mvohm/quadruple/Quadruple.java

Line 1061 in 068dabf

} // public static Quadruple add(Quadruple op1, Quadruple op2) {

Yes, it's an old habit of mine. I feel somewhat uncomfortable when I can't see what method is this that's right above the point where I am now. Yes, IDEs don't modify such comments while refactoring, and yes, outdated comments may not match method signatures, yet they still give a hint.

So I'm not quite resolute. Perhaps I'll remove them later.

[Algomorph]

I'll start a new thread here on the topic of documentation and code comments.
Right now the documentation for public methods already looks excellent:

• Very well written (excellent grammar and word choice!)
• It looks appropriately detailed, complete, and informative.
• It feels succinct

I would need to start using the library to be better qualified to say this, but this is how I feel just by reading it.

Some of the comments for private methods may be improved grammatically and from a lexical perspective, but that hardly seems worth investing a dedicated effort. Perhaps, just keep improving bit-by-bit as you maintain the library in the comping years?