CS11 Java Style Guidelines

Last updated January 22, 2008

Consistently following a clean and clear coding style is very important for any programming project. Some style guidelines are focused on making your programs easier to maintain and less likely to contain flaws. For example, coding styles typically specify what things to comment and how to format those comments. Coding styles also frequently specify what coding patterns should and shouldn't be used. Style guidelines like these are often very important for writing bug-free and maintainable code, and they usually have very good reasons behind them.

By the same token, other aspects of coding style are more aesthetic in nature, and they really don't have so much to do with correctness. However, these guidelines still can improve the maintainability of your code, because all the code looks the same. This makes it much easier for any developer to work on any piece of code. It's just like formatting a document: if the whole document follows the same formatting conventions, it is much easier to read than if each part has its own format!

People also usually end up settling on a "favorite" coding style. (Just like people tend to pick a favorite text editor, email client, etc.) This is great when you have the luxury of controlling the coding standard, but in many circumstances there will already be a coding standard in place. In those cases, it's most important to be flexible.

This page lays out some coding-style guidelines for CS11 Java. By and large, these guidelines are very similar to what you would see in a real Java software project, so it's a great opportunity to practice these habits now. You are strongly encouraged to follow them on your homeworks; if you don't, you are likely to end up with redos!

CS11 Java Style Guidelines

Here is a summary of the important CS11 Java style guidelines:

Indentation

Commenting

Naming

Here is a class that illustrates all three naming conventions:

    /** Class name is UpperCamelCase. **/
    public class WebServer {

	/**
         * Name of constant follows ALL_CAPS naming convention.
         **/
	public static final int DEFAULT_PORT = 80;


        /** HTTP version string, also a constant. **/
        public static final String HTTP_VERSION = "HTTP/1.1";


	/**
	 * Type of field is UpperCamelCase, since all Java
	 * standard classes follow this convention.
         * Field name is camelCase.
         **/
	private ServerSocket sock;


	/**
	 * Constructor uses class name.  Arguments follow
         * camelCase convention.
	 **/
	public WebServer(String hostName, int port) {
            ...
        }


        /** Method name follows camelCase convention. **/
        public HTTPRequest acceptRequest() {
            ...
	}

        ...
    }

Blank Lines

Blank lines can dramatically improve the readability of your program. A program without blank lines looks like a giant run-on sentence. Here are some guidelines for using blank lines.

Spaces

Conditionals, Loops and Blocks

Checkstyle

Checkstyle is an open-source Java style-checking tool. It is amazingly powerful, configurable, and extensible, and reasonably well documented to boot! Many Java projects, both in the software industry and open-source projects, use Checkstyle to verify that their source code satisfies the coding guidelines.

Keep in mind that even though Checkstyle is a powerful tool, it can only understand so much! So there may be important style guidelines to follow that Checkstyle is currently unable to check. Just because your program doesn't make Checkstyle complain, doesn't mean that it has no coding style issues.

Running Checkstyle

You can run Checkstyle on the CS cluster by using this script:

    /cs/courses/cs11/software/cs11javastyle
Simply copy this script file into a convenient location (e.g. ~/cs11/java), and run it from there. It will correctly refer to the Checkstyle installation on the CS cluster. For example, to verify your CS11 Java lab 3 code, you might do this:
    > cp /cs/courses/cs11/software/cs11javastyle ~/cs11/java
    > cd ~/cs11/java/lab3
    > ../cs11javastyle *.java
    [ style issues are reported here ]

As you can see, the script takes a list of one or more .java files to check. You can feed it wildcards. I don't know if this script is smart enough to handle a directory as an argument! So just feed it a list of .java files.


Copyright (C) 2006-2008, California Institute of Technology.