Java Programming Style Guide
Getting the computer to understand your program is no guarantee
that people will be able to follow it. Just as you would edit an
English composition, you should spend time revising a computer program
to make it elegant and readable. The following guidelines will help you
write programs that are easy to read and modify. The grader
may expect your assignments to conform to these style and documentation
conventions.
- Include a header comment at the top of the class containing
the "main"
method
(if application) or at the top of the class that contains the
"extends
Applet" method
(if applet). This header should contain:
- Your name (and the names of any people you work with)
- The course number (e.g., CPSC 211) and your section number
(e.g., 201-203)
- The name of the programming assignment (e.g., Program 1)
- The date of last modification to the file.
- Under the heading "PURPOSE", describe the purpose of the
code in that file. Be brief and informative. Communicate
your approach to solving the problem.
- Under the heading "ASSUMPTIONS", state assumptions you make
regarding
the problem to be solved, the kinds of inputs your program will accept,
and
deviations from the assignment requirements (note that any significant
deviations should be cleared with the instructor in advance.)
This header must include:
- any assumptions made about the input
- limitations of the program with regard to the requirements
- known bugs
Specific assumptions regarding
particular methods may be expressed in block comments above the relevant
methods.
- Include a brief header block
comment at the top of each class that
is not
the "main" or "extends Applet" class AND at the top of each method within
each class. The format is shown below:
//*******************************************************************
// The class or method name
//
// Description of the class or method purpose
//*******************************************************************
- Use inline comments sparingly but whenever necessary.
Use inline comments whenever the meaning of the code is not immediately
obvious from the text. For example, inline comments can be useful to summarize
cases in a conditional expression as follows:
if (xPosition < xLeft) // left of box
...
else if (xPosition > xLeft + width) // right of box
...
else if (yPosition < yBottom) // below box
...
else // inside or above box
...
- Write self-documenting code.
- Choose meaningful names for all variables, parameters, classes, and
methods. Use complete words instead of abbreviations where practical.
- Use named constants instead of sprinkling numbers throughout your code.
Rule of thumb: if a constant is used more than once, give
it a name.
- Avoid repetitious code by writing an appropriately named procedure
and calling it multiple times.
- Follow standard formatting conventions.
- Capitalization:
- variables and method names
- the first letter is lower case, with the first letter of each subsequent
word capitalized
for example, int caloriesFromFat = 18;
- class names
- the start of each word is capitalized
for example, public class VelocityVector {
- constants
- the entire word is capitalized
for example, public final double PI = 3.14159;
- Indentation:
- braces
- the open brace ({) goes at the end of the line before the start of
the code block.
the close brace (}) goes on its own line, indented to match the beginning
of the line containing the corresponding open brace, and include a descriptor
on the closing brace line that indicates which opening brace it matches
- code inside braces
- indent one level (about 3 spaces)
for each level of curly braces ({})
- code inside conditional statements and loops
- indent one level for lines of code in conditional statements and loops; omitting
curly braces when the conditional or loop contains a single statement is possible, but
curly braces can be helpful in future coding and can aid in debugging
- continued lines
- when a statement continues across two or more lines, indent the second
and remaining lines an equal amount past the start of the first line of
the statement.
Example of proper indentation technique:
public static boolean withdraw (int requestedAmount) {
if (balance < requestedAmount) {
return false;
} // end if
else {
balance = balance - requested amount;
System.out.println("Withdrawal of $" + requestedAmount +
" successful, leaving $" +
balance + ".");
return true;
} // end else
} // end method
- Order of variables and methods:
- constants
- if you define any constants, they should go first, with public constants
before private ones
- class variables (static variables)
- if you define any static variables, put them immediately after the
constants, listing the public variables first
- instance variables
- should follow the class variables, with the public ones first
- constructors
- should precede all other methods
- public accessors
- should immediately follow the constructors
- other methods, public and private
- can be listed in any logical order, with related methods near each
other
- the toString method
- should be last so people can find it quickly
- local variables
- should be declared as close as possible to their point of use.
- for example, a variable used as a counter in a for loop can be declared as follows:
for (int i = 0; i < 10; i++)
- Use common sense.
Remember that this style guide is only a guide. Your primary
concern should be making sure that others can read and understand the text
of your program. If you think an additional comment or particular organization
will get your ideas across more effectively, do it. However, if you are
considering deviating significantly from the guidelines or if you are in
doubt about something, please discuss it with us first.
This style guide was adapted by Jenny Walter and Jennifer Welch
from one prepared by Prof. Ken Goldman
at Washington University at St. Louis.