Java Coding Standard
Explanation
When you write the comments this way, you can automatically generate web pages that describe your classes and methods.
If you look at the Java API, you can see what these web pages look like.
This style of writing comments is called "javadoc" (for "java documentation").
Javadoc is the industry standard for Java program comments.
When you use Javadocs in your program, you can create your own webpages from the
program, similar to the Java API.
For example, this example program
ArraysAndMethods.java
generates the following
ArraysAndMethods API (Application Program Interface).
To create a webpage from the Javadocs in your program, open your program in jGRASP,
click "File", then click "Generate Documentation".
You should see any Javadoc errors in the "Compile Messages" window at the bottom.
Then, a browser should automatically open with a webpage describing your program!
The Java Coding Standard is based on the Java language coding conventions.
For more details on the Java language coding conventions, see Java Code Conventions - Oracle
Basic Coding Rules to Follow
- Use descriptive and appropriate names for all identifiers (variables, method names, class names, constants, etc.).
-
Comment every 3-7 lines of code.
-
Be neat.
Identifier Naming and Capitalization
Guidelines
-
Use descriptive names for all variables, function names, constants, and other identifiers.
-
Use single letter identifiers only for the counter in loops.
-
Class names start with an upper case letter.
-
Variable names start with a lower case letter. (Variables include parameters, local variables, and data fields. Exception: use UPPER_CASE for constants - final variables.)
-
Method names start with a lower case letter.
-
Multi-word identifiers are internally capitalized.
-
Do not use hyphens or underscores to separate multi-word identifiers (except for constants, which have all upper case letters).
Example
float sumOfSquares = 0;
final int DAYS_IN_YEAR = 365; //Use UPPER_CASE for constants (final variables)
|
Counter Example
float Sum = 0;
float sumofsquares = 0;
float sum_of_squares = 0;
float x = 0;
|
Comments: Classes
Guidelines
-
Every class should be preceded with a descriptive comment using the "JavaDoc" notational convention.
-
The comment should describe its purpose of the class.
-
Class names start with an upper case letter.
Example
/**
* Stores the first, middle, and last names for a president.
*/
class President {
//code...
}
|
Comments: Methods
Guidelines
-
Every method definition should be preceded with a descriptive comment using the "Javadoc" notational convention.
-
The comment should include a description of the method, the name and description of each parameter,
a description of the return value, and the name and description of any exceptions thrown within the method using Javadoc keywords and formatting.
-
-
Detailed description line by line:
-
Begins with a slash, followed by two asterisks (/**)
-
One asterisk (*)
-
One asterisk (*), followed by @param, followed by the name of the parameter, followed by a description of the parameter
(Omit if there are no parameters. Use one line for each parameter, so two parameters will have two lines. 3 parameters will have 3 lines. Etc.)
-
One asterisk (*), followed by return, followed by a description of the return variable
(Omit if the return value is void.)
-
One asterisk (*), followed by @exception,
followed by the class of the exception,
followed by a description of when the exception is thrown.
Only checked exceptions are required to be listed.
Unchecked exceptions are not required to be listed.
Omit exceptions if there are no exceptions that are thrown.
(In other words, if you catch the exception within the method,
you do not need to list the exception.)
Use one line for each exception,
so two exceptions will have two lines.
3 exceptions will have 3 lines.
Etc.
-
Ends with one asterisk, followed by one slash (*/)
Example
/**
* Prints a word, prints a number, and returns integer 1
*
* @param word any string of Class String
* @param number an integer of any value
* @return the integer 1
* @exception MyException if the word starts with the letter 'z'
* @exception YourException if the number is a zero(0)
*/
public static int method1(String word, Integer number) throws MyException, YourException{
//code...
if(word.charAt(0) == 'z'){
//thrown, but not caught in method, so put in JavaDocs above
throw new MyException();
}
if(number == 0){
//thrown, but not caught in method, so put in JavaDocs above
throw new YourException();
}
try{
int x = 5 / 0;
}
catch(ArithmeticException exception){
System.out.println("ERROR: Division by zero! " + exception);
}
return 1;
}
|
Comments: Public variables
Guidelines
-
Every public variable should be preceded with a descriptive comment using the "JavaDoc" notational convention.
The comment should describe the purpose for the public variable.
Example
/** Toggles between frame and no frame mode. */
public boolean frameMode = true;
|
Comments: In-line
Guidelines
-
In-line comments should be used to explain complicated sections of code, such as loops.
Use the // comment delimiter for in-line comments.
Do not comment generally known features of the java language.
Example
// Do a 3D transmogrification on the matrix.
for (int i = 0; i < matrix.length; i++) {
for (int j = 0; j < matrix.length; j++) {
for (int k = 0; k < matrix.length; k++) {
values.transmogrify(matrix[i],matrix[j],matrix[k]);
}
}
}
|
Counter Example
i++; // increments i
// the variable "i" loops from 0 to the length of matrix
for (int i = 0; i < matrix.length; i++) {
// ...
}
|
Spacing: Between lines
Guidelines
-
Use two blank lines to separate each method within a class definition.
Use one blank line to separate logical sections of code within a method.
Example
public static void main(String[] arg) {
System.out.println("Hello" + " " + "World");
}
public void foo() {
// ...
}
|
Spacing: Within lines
Guidelines
-
Put a single space before every "{".
-
Separate all binary operators, such as "+", "-", "*", "/", "%", etc., with a single space.
The exception is unary operators, such as "++", "--", unary minus "-", etc, which do not need to be separated with a single space.
Example
public static void main(String[] arg) {
System.out.println("Hello" + " " + "World");
}
|
Counter Example
public static void main(String[] arg){
System.out.println("Hello"+" "+"World");
}
|
Indentation
Guidelines
-
Indent two spaces when beginning a new block.
-
Open braces (i.e. "{") do not start a new line.
-
Close braces (i.e. "}") do start a new line, and are indented with the code they close.
-
Comments line up with the block they comment.
Example
for (int i=0; i < args.length; i = i + 1) {
vals.insertElementAt(new Float (args[i]), i);
// Transmogrify is incremental and more efficient inside the loop.
vals.transmogrify();
}
|
Counter Example
for (int i=0; i < args.length; i = i + 1)
{
vals.insertElementAt(new Float (args[i]), i);
// Transmogrify is incremental and more efficient inside the loop.
vals.transmogrify();
}
|
Class, Package, and Method Naming and Capitalization
Guidelines
-
Classes begin with a capital letter.
-
Packages are all lower case.
-
Methods begin with a lower case letter.
-
Multi-word identifiers are internally capitalized in methods (CamelCase).
Example
package foo.bar.baz;
public class MeanStandardDeviation
private Vector getNewVector(Vector oldVector) {
|
Counter Example
package Foo.Bar.Baz;
public class Meanstandarddeviation
private Vector GetNewVector(Vector oldVector) {
|
Program Modules
Guidelines
-
Lines of code should be kept short, generally less than 80 or 100 characters wide.
-
Each public class is contained in a separate file.
-
Each file has the name of the public class contained within it.
-
Avoid the use of the default package.
Other References
Website
Click to validate the HTML code
Click to validate the CSS code