<< Back

How To Document and Organize Your Java Code

On This Page


1. Introduction

Programming style is about how you organize and document your code. Style is more than a matter of aesthetic interest. A program written following a consistent style is easier to read, easier to correct and easier to maintain.

A program may be written only once, but is read many times:

Anything that makes a program more readable and understandable saves lots of time, even in the short run.

This course follows the industry standard Code Conventions for the Java Programming Language. Exceptions to this standard are listed within this document. Some portion of the grade for most programming assignments is based on conformance to these standards.

Running CheckStyle

CheckStyle is a program that will check your source code for errors. Here are some instructions for running CheckStyle at the command line:

  1. Copy the checkstyle-all-4.4.jar and grade_checks.xml into the same directory as your Java source files
  2. Open a console (terminal) window and type the following command:

    java -jar checkstyle-all-4.4.jar com.puppycrawl.tools.checkstyle.Main -c grade_checks.xml *.java

This will test all the *.java files in the directory. If you want to restrict the files you will need to specify the file name rather than use *.java.

2. Naming Conventions

2.1. Use Meaningful Names

Choose names that suggest their purpose. Good names help you understand the problem you are solving.

2.2. Variable Names

Start with a lower-case letter and use uppercase letters as separators. Do not use under bars ('_').

int myVar

2.3. Constant Names

Use all capital letters and use under bars ('_') as separators.

final int MY_CONST = 1;

2.4. Method Names

Start with a lower-case letter and use uppercase letters as separators. Do not use under bars ('_').

int myMethod()

2.5. Class Names

Start with an upper-case letter and use uppercase letters as separators. Do not use under bars ('_').

public class MyClassName

3. Comments

Comments are explanatory notes for the humans reading a program. With good name choices, comments can be minimal in a program. The only required comments are block comments just before the class declaration (after any import statements) and just before each method declaration.

Other than block comments, one other time to add comments is when your code is unusual or obscure. When something is important and not obvious, it merits a comment.

3.1. Block Comments

Javadoc is a program that examines the declarations and documentation comments of your code to produce a set of HTML pages. These pages describe your code to other programmers. For an example of the documentation produced, see the Java API documentation.

Some of the Javadoc is derived from specially-formatted block comments, which you create as follows:

3.2. File Comment Block

Every source code file (*.java) must have a Javadoc comment block just before the class declaration containing the course number, assignment number, name of the file and purpose of the file. One or two lines is usually sufficient to explain the purpose. In addition, you must add the author tag containing your name and the version tag containing the date the assignment is due. For example:

import javax.swing.*;

/**
 * CS-12J Asn 3
 * HelloWorld.java
 * Purpose: Prints a message to the screen.
 *
 * @author Jane User
 * @version 1.0 8/20/03
 */
public class HellowWorld {

The following tags must be used always:

3.3. Method Comment Block

Every method must have a Javadoc comment block before the method. For example:

/**
 * Read a line of text from the shell console.
 *
 * @return A String input by the user.
 */

The first line is a description of how to use the method.

Where appropriate, the following tags must be used:

3.4. Example Program Documentation

For an example of a properly-documented source code, click here.

4. Curly Braces

A fervent issue of great debate in programming circles is placement of curly braces. The Java style is to place the initial brace on the same line as the keyword and the trailing brace on its own line but lined up with the keyword. For example:

if (condition) {
    ...
}

while (condition) {
    ...
}

4.1. When Braces are Needed

All if, while and do statements must either have braces or be on a single line. This helps to make sure someone adding a line of code does not forget to add braces.

5. Whitespace

Always layout your source code so that elements that are part of a group go together.

5.1. No Tab Character

Do not have any tab characters in your source code. It is difficult to impossible to read source code if your tab settings are different than the authors.

The easy way to remove tabs is to set your text editor to substitute the correct number of spaces for a tab character. See the instructions for both jEdit and TextPad for setting up these editors. For other editors, you will need to search for the setting.

5.2. Line Length

Limit your line length to 80 characters since longer lines may cause problems with many text editors and other tools.

5.3. Spacing Around Operators

Always put spaces before and after binary operators. This improves the readability of expressions. For example:

int c = -a * b - d;

5.4. Indentation

Always indent within curly braces. Use four (4) spaces for each indentation level. For example:

void func() {
    if (something happened) {
        if (another thing happened) {
            while (more input) {
                ...
            }
        }
    }
}

5.5. if-else-if-else Formatting

Always line up if statements with the curly braces for their associated else statement. Specifically, place the initial brace on the same line as the keyword and the trailing brace inline on the same line as the next statement. For example:

if (condition) {               // Comment
    ...
} else if (condition) {        // Comment
    ...
} else {                       // Comment
    ...
}

6. Additions and Exceptions to the Javadoc Standards

Most professional Java programmers follow these conventions even though they are not listed in the Code Conventions for the Java Programming Language.

6.1. No Magic Numbers

A magic number is a numeric literal that is not defined as a constant. It's magic because no one has a clue what it means after 3 months, including the author. From widespread use, -1, 0, 1, and 2 are not considered magic numbers.

Whenever you assign a number to a variable, use a constant instead. In Java, you declare constants, which are variables that cannot change, using the keyword final. You may use local constants within methods or member constants declared outside of any method. Usually, you declare member constants as a public static final member variable.

public static final int MY_CONSTANT = 10;

Because of their special meaning, write constants in all upper case and use under bars ('_') as separators.

6.2. Method Length

Methods must be no more than 150 lines long. If a method becomes very long it is hard to understand. Instead, you should create smaller methods that focus on individual tasks.

6.3. Tab Character

Do not have any tab characters in your source code. It is difficult to impossible to read source code if your tab settings are different than the authors.

7. Creating Javadoc

What is the point of formatting documentation in this manner? So we can create and view Javadoc from our own code!

You can use the javadoc tool to generate documentation from Javadoc comments using the following syntax:

C:\programDir>javadoc -d docDir listOfClassNames

For Example

  1. Copy the file to the desired directory
  2. Open a command window, navigate to the directory and enter
    javadoc -d ./ Console.java
    • Creates the javadoc in the current directory (./)
  3. Open the index.html file that is created in a browser.

Further Information

8. Automatic Style Checking

Why can't the computer check my style for me? The answer is that it can! You can find a number of programs that check your programming style. The best that I have seen is called Checkstyle. It runs both standalone (by itself) and within other tools, such as text editors. I use it with both jEdit and TextPad.

<< Back