This appendix contains a series of guidelines that describe how to organize and

format Java source code. They are designed to make programs easier to read and
maintain. Some guidelines can be attributed to personal preferences and could be
modified. However, it is important to have some standard set of practices that
G
make sense and to follow them carefully. The guidelines presented here are fol-

java coding guidelines

lowed in the example code throughout the text and are consistent with the Java
naming conventions.
Consistency is half the battle. If you follow the same rules throughout a pro-
gram, and follow them from one program to another, you make the effort of
reading and understanding your code easier for yourself and others. It is not
unusual for a programmer to develop software that seems straightforward at the
time, only to revisit it months later and have difficulty remembering how it
works. If you follow consistent development guidelines, you reduce this problem
considerably.
When an organization adopts a coding standard, it is easier for people to work
together. A software product is often created by a team of cooperating develop-
ers, each responsible for a piece of the system. If they all follow the same devel-
opment guidelines, they facilitate the process of integrating the separate pieces
into one cohesive entity.
You may have to make tradeoffs between some guidelines. For example, you
may be asked to make all of your identifiers easy to read yet keep them to a rea-
sonably short length. Use common sense on a case-by-case basis to embrace the
spirit of all guidelines as much as possible.
You may choose, or be asked, to follow this set of guidelines as presented. If
changes or additions are made, make sure they are clear and that they represent
a conscious effort to use good programming practices. Most of these issues are
discussed further in appropriate areas of the text but are presented succinctly
here, without elaboration.

design guidelines
A. Design Preparation
1. The ultimate guideline is to develop a clean design. Think before you start
coding. A working program is not necessarily a good program.
2. Express and document your design with consistent, clear notation.
706 APPENDIX G java coding guidelines

B. Structured Programming
1. Do not use the continue statement.
2. Only use the break statement to terminate cases of a switch statement.
3. Have only one return statement in a method, as the last line, unless it
unnecessarily complicates the method.
C. Classes and Packages
1. Do not have additional methods in the class that contains the main
method.
2. Define the class that contains the main method at the top of the file it is
in, followed by other classes if appropriate.
3. If only one class is used from an imported package, import that class by
name. If two or more are imported, use the * symbol.
D. Modifiers
1. Do not declare variables with public visibility.
2. Do not use modifiers inside an interface.
3. Always use the most appropriate modifiers for each situation. For exam-
ple, if a variable is used as a constant, explicitly declare it as a constant
using the final modifier.
E. Exceptions
1. Use exception handling only for truly exceptional conditions, such as ter-
minating errors, or for significantly unusual or important situations.
2. Do not use exceptions to disguise or hide inappropriate processing.
3. Handle each exception at the appropriate level of design.
F. Miscellaneous
1. Use constants instead of literals in almost all situations.
2. Design methods so that they perform one logical function. As such, the
length of a method will tend to be no longer than 50 lines of code, and
usually much shorter.
3. Keep the physical lines of a source code file to less than 80 characters in
length.
4. Extend a logical line of code over two or more physical lines only when
necessary. Divide the line at a logical place.
 APPENDIX G java coding guidelines 707

style guidelines
A. Identifier Naming
1. Give identifiers semantic meaning. For example, do not use single letter
names such as a or i unless the single letter has semantic meaning.
2. Make identifiers easy to read. For example, use currentValue instead of
curval.
3. Keep identifiers to a reasonably short length.
4. Use the underscore character to separate words of a constant.
B. Identifier Case
1. Use UPPERCASE for constants.
2. Use Title Case for class, package, and interface names.
3. Use lowercase for variable and method names, except for the first letter of
each word other than the first word. For example, minTaxRate. Note that
all reserved words must be lowercase.
C. Indentation
1. Indent the code in any block by three spaces.
2. If the body of a loop, if statement, or else clause is a single statement
(not a block), indent the statement three spaces on its own line.
3. Put the left brace ({) starting each new block on a new line. Line up the
terminating right brace (}) with the opening left brace. For example:

while (value < 25)

{
value += 5;
System.out.println (“The value is ” + value);
}

4. In a switch statement, indent each case label three spaces. Indent all
code associated with a case three additional spaces.
D. Spacing
1. Carefully use white space to draw attention to appropriate features of a
program.
2. Put one space after each comma in a parameter list.
3. Put one space on either side of a binary operator.
708 APPENDIX G java coding guidelines

4. Do not put spaces immediately after a left parenthesis or before a right

parenthesis.
5. Do not put spaces before a semicolon.
6. Put one space before a left parenthesis, except before an empty parameter
list.
7. When declaring arrays, associate the brackets with the element type, as
opposed to the array name, so that it applies to all variables on that line.
For example:
int[30] list1, list2;

8. When referring to the type of an array, do not put any spaces between the
element type and the square brackets, such as int[].
E. Messages and Prompts
1. Do not condescend.
2. Do not attempt to be humorous.
3. Be informative, but succinct.
4. Define specific input options in prompts when appropriate.
5. Specify default selections in prompts when appropriate.
F. Output
1. Label all output clearly.
2. Present information to the user in a consistent manner.

documentation guidelines
A. The Reader
1. Write all documentation as if the reader is computer literate and basically
familiar with the Java language.
2. Assume the reader knows almost nothing about what the program is sup-
posed to do.
3. Remember that a section of code that seems intuitive to you when you
write it might not seem so to another reader or to yourself later. Docu-
ment accordingly.
 APPENDIX G java coding guidelines 709

B. Content
1. Make sure comments are accurate.
2. Keep comments updated as changes are made to the code.
3. Be concise but thorough.
C. Header Blocks
1. Every source code file should contain a header block of documentation
providing basic information about the contents and the author.
2. Each class and interface, and each method in a class, should have a small
header block that describes its role.
3. Each header block of documentation should have a distinct delimiter on
the top and bottom so that the reader can visually scan from one con-
struct to the next easily. For example:

//*****************************************
// header block
//*****************************************

D. In-Line Comments
1. Use in-line documentation as appropriate to clearly describe interesting
processing.
2. Put a comment on the same line with code only if the comment applies to
one line of code and can fit conveniently on that line. Otherwise, put the
comment on a separate line above the line or section of code to which it
applies.
E. Miscellaneous
1. Avoid the use of the /* */ style of comment except to conform to the
javadoc (/** */) commenting convention.
2. Don’t wait until a program is finished to insert documentation. As pieces
of your system are completed, comment them appropriately.