2.15. Programming Errors

[Page 55 ( continued )]

2.14. Programming Style and Documentation

Programming style deals with what programs look like. A program can compile and run properly even if written on only one line, but writing it all on one line would be bad programming style because it would be hard to read. Documentation is the body of explanatory remarks and comments pertaining to a program. Programming style and documentation are as important as coding. Good programming style and appropriate documentation reduce the chance of errors and make programs easy to read. So far you have learned some good programming styles. This section summarizes them and gives several guidelines. More detailed guidelines on programming style and documentation can be found in Supplement I.D, "Java Coding Style Guidelines," on the Companion Website.

2.14.1. Appropriate Comments and Comment Styles

Include a summary at the beginning of the program to explain what the program does, its key features, its supporting data structures, and any unique techniques it uses. In a long program, you should also include comments that introduce each major step and explain anything that is difficult to read. It is important to make comments concise so that they do not crowd the program or make it difficult to read.

Use javadoc comments ( /** ... */ ) for commenting on an entire class or an entire method. These comments must precede the class or the method header, and can be extracted in a javadoc HTML file. For commenting on steps inside a method, use line comments ( // ).

2.14.2. Naming Conventions

Make sure that you choose descriptive names with straightforward meanings for the variables , constants, classes, and methods in your program. Names are case-sensitive. Listed below are the conventions for naming variables, methods, and classes.

• Use lowercase for variables and methods. If a name consists of several words, concatenate them into one, making the first word lowercase and capitalizing the first letter of each subsequent word; for example, the variables radius and area and the method showInputDialog .

• Capitalize the first letter of each word in a class name; for example, the class names ComputeArea , Math , and JOptionPane .

• Capitalize every letter in a constant, and use underscores between words; for example, the constants PI and MAX_VALUE .

---

[Page 56]

Tip

It is important to become familiar with the naming conventions . Understanding them will help you to understand Java programs. If you stick with the naming conventions, other programmers will be more willing to accept your program.

Caution

Do not choose class names that are already used in the Java library. For example, since the Math class is defined in Java, you should not name your class Math .

Tip

Avoid using abbreviation for identifiers. Using complete words is more descriptive. For example, numberOfStudents is better than numStuds , numOfStuds , or numOfStudents .

2.14.3. Proper Indentation and Spacing

A consistent indentation style makes programs clear and easy to read. Indentation is used to illustrate the structural relationships between a program's components or statements. Java can read the program even if all of the statements are in a straight line, but it is easier to read and maintain code that is aligned properly. Indent each subcomponent or statement two spaces more than the structure within which it is nested.

A single space should be added on both sides of a binary operator, as shown in the following statement:

A single space line should be used to separate segments of the code to make the program easier to read.

2.14.4. Block Styles

A block is a group of statements surrounded by braces. There are two popular styles, next -line style and end-of-line style, as shown in Figure 2.10. The next-line style aligns braces vertically and makes programs easy to read, whereas the end-of-line style saves space and may help avoid some subtle programming errors. Both are acceptable block styles. The choice depends on personal or organizational preference. You should use a style consistently. Mixing styles is not recommended. This book uses the end-of-line style to be consistent with the Java API source code.

---

[Page 57]

Figure 2.10. The opening brace is placed at the beginning of a new line for next-line style and at the end of the line for end-of-line style.

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