M.
Morgenstern
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 a consistent, clear notation.
B. Structured Programming
1.
Have only
one return statement in a method, as
the last line, unless doing so unnecessarily complicates the method.
2.
Avoid
using the continue statement.
3.
Only use
the break statement to terminate cases
of a switch statement.
C. Classes and Packages
1.
Define
the class that contains the main method at the top of the file it is in,
followed by other classes if appropriate.
2.
If only
one class is used from an imported package, import that class by name. If two or
more are imported, use the * symbol.
1.
Do not
declare variables with public
visibility unless you have a good reason for doing so.
2.
Always
use the most appropriate modifiers for each situation.
For example, if a variable is used as a constant, explicitly declare it
as a constant using the final modifier.
3.
Do not
use modifiers inside an interface.
1.
Use
exception handling only for truly exceptional conditions such as terminating
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.
1.
Use
constants (final variables) instead of literals (actual values) in almost all
situations.
2.
Design
methods so that each performs one logical function. As such, the length of a
method will tend to be no longer than 50 lines of code.
3.
Keep each
physical line of a source code file 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.
1.
Give
identifiers semantic meaning. Example: Do not use single letter names such as a
or i.
2.
Make
identifiers easy to read. Example: use current_value
instead of curval.
3.
Keep
identifiers to a reasonable length not unnecessarily long.
4.
Use the
underscore character to separate words of an identifier an alternative is to
capitalize the first letter of each simple word (other than the first) in a compoundLongIdentifierName.
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. Note that all reserved words must be
lowercase.
1.
Indent
the code in any block a consistent number of spaces three spaces are recommended.
2.
Put the
left brace ({ ) starting each new
block on the same line as the construct that it defines, such as a class,
method, loop, if statement, or else
clause. The terminating right brace ( })
should line up with the beginning of the construct.
Example:
while (total
< 25) {
total +=5;
System.out.println (The
total is + total);
}
3.
Put the else
clause of an if statement on the same
line as the terminating right brace (})
of the block defining the body of the if
clause. If the if clause contains a
single statement, begin the else
clause on a new line. Examples:
if (expr)
{
if (expr)
statement1:
statement1;
statement2;
else
} else
statement2;
statement3;
4.
If a
single if statement serves as the body
of an else clause, the if
statement should follow the else on
the same line, and the body of the if should
be indented only three spaces. This is an exception to guideline C.2. above, and
keeps nested if statements from
cascading too quickly to the right.
Example:
if (expr1)
{
statement1;
statement2;
} else
if (expr2)
statement3;
else if
(expr3)) {
statement4;
statement5
} else
{
statement6;
statement7;
}
5.
In a switch
statement, indent each case label
three spaces. Indent all code associated with a case three additional spaces.
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.
Some people use a space only one side of string concatenation +.
4.
Do not
put spaces immediately after a left paren or before a right paren.
5.
Do not
put spaces before a semicolon.
6.
Put one
space before a left paren, 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 the line.
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[].
1.
Do not
condense.
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.
1.
Label all
output clearly.
2.
Present
information to the user in a consistent manner.
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 supposed to do.
3.
Remember
that a section of code that seems intuitive to you when you write it might not
be to another reader or to yourself later.
Document accordingly.
1.
Make sure
comments are accurate.
2.
Keep
comments updated as changes are made to the code.
3.
Be
concise but thorough.
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 construct to the next
easily. Example:
/
/ ==========================================================
/
/
header block
/
/ ==========================================================
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.
3.
Put a
comment on the line with the terminating brace of each class, interface, method,
and constructor to identify the name of the construct being closed.
1.
Dont
wait until a program is finished to insert documentation. As pieces of your
system are completed, comment appropriately.
2.
Some
people prefer to not use of the /*
*/ style of comment, rather they use the // form above, so that each line
is identified as a comment (rather than looking for /* on some previous line).
3.
Use
JavaDoc style comments for the header block and where approriate, once you are
familiar with JavaDoc.
[1] Adapted for classroom use only, from: Java Software Solutions, J. Lewis & W. Loftus, Addison-Wesley.