A.10. Coding Conventions

This section describes the standard coding style we will use in this book. You or your instructor may have slightly different preferences. Since coding style exists to make programs easier for humans to read, it is only important that we are consistent and stay fairly close to what most of the Java community does.

Identifiers

Names of constants are in all caps, with words separated by underbars:

PI
SCREEN_WIDTH

Type parameters (Section 4.1) have one-letter upper-case names. Typical names include E for element, K for key, and V for value.

Names of classes, constructors (Section 1.2), and interfaces (Section 2.3) have words run together, with the first letter of each word capitalized:

Hello
PolyhedralDie

All other identifiers are formatted the same way, but the first word is not capitalized:

args
bestSoFar

A few standard identifiers are given in Figure A-22.

Figure A-22. Widely used identifiers.

Identifier	Use
i, j, k	loop variable, index into array
m, n	integer in mathematical function
tally	running count of something
target	element being searched for in, removed from, or added to a data structure
that	object being compared with this
result	value to be returned
x, y	double in mathematical function

 

Blocks

We always use curly braces for the bodies of loops and if statements. It is technically legal to leave these out if the body consists of a single statement, but it is a very bad idea. If we later go back and add another line (for example, an invocation of System.out.println() to print a debugging message), we might run into the problem shown in Figure A-23.

Figure A-23. These two for loops are not equivalent.

1 for (int i = 0; i < 5; i++) {
2 System.out.println("i is " + i);
3 System.out.println("I'm in the loop!");
4 }
5
6 for (int i = 0; i < 5; i++)
7 System.out.println("i is " + i);
8 System.out.println("I'm in the loop!");

Despite the deceptive indentation, these loops are not equivalent. In the second loop, the body of the loop is only line 7. Line 8 is not in the loop, so it is executed only once.

Comments

We include a javadoc comment before each class, interface, field, and method, with the exception of some methods which are merely implementing a method from an interface (Section 2.3) or overriding a method from a superclass (Section 3.1). A javadoc comment begins with /** and ends with */.

The wonderful thing about javadoc comments is that they can be used to generate automatic documentation.

Warning: Do not perform this next step if you have any .html files in the same directory as your .java files. The javadoc program may overwrite them!

By this point you presumably have several .java files in your directory. To generate documentation for all of them, use the command:

javadoc -public *.java

This generates a number of .html files. Open the file index.html in your web browser. Click on the name of a class to see its documentation. Part of the documentation for the Circle class (Figure A-17), in the file Circle.html, is shown in Figure A-24.

Figure A-24. Part of the automatically-generated javadoc documentation for the Circle class.

(This item is displayed on page 541 in the print version)

A second type of comment is the C++-style comment which begins with // and goes to the end of the line. We occasionally use this to point out the major sections of a method, explain a particularly cryptic line, or note that some code has been left out of a figure for brevity.

Access Levels

Access levels are discussed in Chapter 3. We adopt the following conventions:

All fields are private, except for constants, which are public.

Methods are either public or protected.

All classes and interfaces are public.

Arrangement of Class Members

The elements of a class appear in the following order:

1. Static fields
2. Non-static fields
3. Constructors
4. Other methods
5. The main() method

Within each section, members appear in alphabetical order, unless some other order (particularly for fields) would be clearer.

Exercises

A.23	Discuss the advantages and disadvantages of establishing coding conventions for a group project.
A.24	In what way does the method name println() violate the standards?