A non-controversial topic generates surprising confusion . . .

A final word on a troublesome int

©Conrad Weisert, March 17, 2012

A textbook gaffe

Our Information Technology profession is filled with controversial issues and with concepts that are subject to subtle shades of interpretation. The meaning of the int primitive data type in Java is not one of them. A Java1 int is simply a 32-bit signed binary integer. It is never anything else.

Nevertheless, a recent undergraduate course textbook2 manages to confuse readers with this bit of function documentation3:

* @param n the non-negative integer in decimal notation
  public static String fctnName (int n)

It's hard to explain such a gaffe. Perhaps the example was adapted and carelessly edited from a similar routine coded in another programming language.

This example set off a sprited discussion among students in an intermediate-level programming course. Some of them speculated on how one might stretch the meaning of the comment to explain the author's intent.


None of those speculations could be justified. The quoted documentation is simply erroneous and certainly not worth a debate.

In particular, the following considerations, which a few students raised, have no relevancy to the issue:

If we delete the last three words from the comment line, the example will make sense. It may have other flaws, but they're not apparent from this small fragment.

Role of binary integers

Binary integers of various sizes are a fundamental built-in data type of the C family of programming languages. They are the only legitimate operands for these operators:
<<left shift
>>right shift
|bitwise OR
&bitwise AND
^bitwise XOR

Furthermore, there is no built-in decimal data type4 in C, C++, or Java. A programmer using those languages must confront and master binary integers and exploit them in everyday programming.

1—Also C#. In C/C++ a binary integer, but its length depends on the platform, commonly 16 or 32, and the programmer can specify unsigned
2—William J. Collins: Data Structures and the Java Collections Framework (third edition), 2011, Wiley, ISBN-978-0-470-48267-4, p. 163
3—Using the JavaDoc conventions.
4—In particular the IEEE standard floating-point (Java's double) also uses binary representation. That's why 0.1, for example, isn't exact.

Return to articles on technical articles.
Return to IDI home page.