Re: BitSet vs BigInteger (false Android doc)
On 9/6/2011 3:02 AM, Jan Burse wrote:
....
Maybe this is based on a general assumption that javadocs
are above critique. But I think javadocs can be buggy
in the same way that code can be buggy. They are just
written by someone, and it can be that this someone had
good intentions, but nevertheless something went wrong.
....
There are actually two categories of documentation involved here,
prescriptive standards and implementation descriptions.
The prescriptive standards are inherently "right", regardless of whether
or not I agree with the decisions involved, in the sense that they
define Java. A BigInteger implementation whose bit operations do not
follow 2's complement semantics would be wrong by definition. A Java
core API implementer does not have the option of changing the
documentation rather than code.
The descriptive information can indeed be wrong. I've written material
that went into Sun Microsystems technical documentation in other areas,
not Java, and I can definitely make mistakes.
However, in this case I've examined ground truth in the sense of reading
the Android BigInteger implementation. It definitely uses the simple,
reliable, but inefficient approach of converting to 2's complement from
internal representation to do bit operations. Given that, it seems
helpful of them to point out the inefficiency and advise use of BitSet
instead.
You may not agree with the trade-off they made, but that would not make
the note false.
Patricia