Lab03: Style guide and Checkstyle

Code Quality 


Virtually every organization that does software development has strict guidelines on how to format source code. Here are two examples of "industrial strength" Java style guides:

This course will more or less follow a simplified version of these guidelines. Rather than memorize a long list of rules, you should develop good habits and intuition when it comes to style.

Checkstyle is a tool that can be used to determine if your source code follows a set of style rules. It also checks for common programming mistakes, such as empty statements and shadow variables.

Checkstyle logo

Running Checkstyle from command line

Download these two files into the same directory as your code:

Make sure the two files above and your .java file(for example Hello or from the last lab, or the in the next section below are all in the same directory).

Open a terminal and use the following command to run Checkstyle:

java -jar checkstyle-*-all.jar -c cs149wc.xml *.java

Note the * characters are wildcards that match whatever version of Checkstyle you have and whatever java source files are present. The output indicates the file and line number of each problem. This example refers to a method beginning on line 93, column 5 of Missing a Javadoc comment

If you apply Checkstyle to your source code regularly, you will likely internalize good style habits over time. Note however that Checkstyle does NOT evaluate the quality of comments, meaning of variable names, and placement of declarations.

Running Checkstyle Through JGrasp

After you have downloaded the Checkstyle .jar file and the .xml configuration file, open jGRASP and select:
Tools -> Checkstyle -> Configure.

Configure screenshot

In the "Checkstyle Tool Settings" dialog box set "Checkstyle Home" to

be the folder containing the .jar file(probably /usr/home/stu/stu-f/eid/cs149/lab03), and "Checks File" to be the cs149wc.xml file, then click "OK".  TIP: You can use the HOME button when hitting the Browse button on the checkstyle dialog to go to your users home folder in Linux as shown below

Home Button

If all went well, you should see two new buttons on the jGRASP toolbar: Checkbutton and Check folder image. Clicking the first button will run Checkstyle on the current file in the editor window. Clicking the second button will run Checkstyle on all of the Java files in the current directory.

Also, You may want to setup JGrasp to indent properly and handle tabs well. In the JGrasp menu select:
Settings->CSD Window settings -> Workspace.  Select the Soft Tabs checkbox then set tab size to 4.

Example Program

If you haven't already, you should create a top-level CS149 folder to organize all your labs and other assignments for the semester. Then create aLab03 folder for today's lab. (If you logged in as student today, please log out and log back in with your own account.)

Create a new folder in your stu server called lab3 and copy the code from the stu server /cs/shr/code/ [ cp /cs/shr/code/ ] into your new folder.

Submission: At the end of class today, or by 11:00 PM if you would like more time, submit a corrected version of via WebCat. Your code must pass Checkstyle without any warnings AND meet all the requirements outlined below. (It must also compile and run correctly; don't change the program's behavior.)  If you cannot get this working in WebCat you may upload to Canvas, but points will be deducted.

Collaboration: You are encouraged to work with another student to complete this lab. Each of you should submit your own copy of the program. It's okay if your files are similar or identical, as long as both of your names are present at the top.

A. Comments

  1. Every class must contain a Javadoc comment with the following three elements.
  * Overall description of the class goes here.
  * @author Your name goes here
  * @version Due date goes here
  * Acknowledgements: I received no outside help on this assignment and have 
  * abided by the JMU Honor Code.
  1. All methods (including main) must contain an applicable Javadoc comment.
 * Overall description of the method goes here.
 * @param paramterName describe each input parameter
 * @param anotherParam use a separate line for each
 * @return describe the value that this method returns
  1. In-line comments (//) should describe major structures and steps within a method.
  2. All comments should use normal English spelling and grammar. Phrases are okay.
  3. Comments must come before the code that they are describing or on the same line.

B. Names

  1. All names should be descriptive and readable. (subTotal rather than s,  grade rather than grd)
  2. Multiple-word names should use capital letters to separate words. (subTotal, not sub_total)
  3. Variable and method names should begin with a lowercase letter, and:
    • Variable names should be nouns or noun phrases. (studentName or subTotal)
    • Method names should be verbs or verb phrases. (printLine or addColumn)
  4. Class names should begin with a capital letter and use title case. (HelloWorld)
  5. Constant names should be all caps with an underscore separator. (PI or INTEREST_RATE)

C. Declarations

  1. All constants should be named and initialized at the top of the method in which they are used.
final double CENTIMETERS_PER_INCH = 2.54;
centimeters = inches * CENTIMETERS_PER_INCH;    // NOT inches * 2.54;
  1. All variables should also be declared at the top of the method, directly after any constant declaraions.
  2. It is strongly recommended (in CS 149) to separate variable declaration and initialization statements.
Scanner input = new Scanner(;    // discouraged

Scanner input;
input = new Scanner(;
  1. Each declaration should be on its own line. Comment to the right if the name is not self-explanatory.

D. Literals

  1. Numeric literals should be of the correct type for the context in which they are used.
// integer expressions should use integer literals
int a;
double b;
a = 2;
b = 2.0;

// double expressions should use double literals
double x;
double y;
double average;
average = (x + y) / 2.0;    // NOT 2, which is an integer

E. Indentation

  1. Subsections of code should be indented consistently with four spaces.
  2. Always use four space characters, not tab characters, for indentation.
  3. Statements too long for one line should be indented on subsequent lines.
  4. All blocks of code (even if one line) should be surrounded by curly braces.
  5. Left braces must appear on the same line as the structure header.

F. Whitespace

  1. There should be a space after cast operators, commas, and //'s.
  2. Use whitespace to separate logical segments of code. There should be a blank line after variable declarations.
  3. Lines should be kept to a short length (< 80 chars). You should be able to see the full line in your text editor.
  4. Binary operators should be separated from their operands by a single space. (sum = myGrade + yourGrade;)
  5. One exception is the dot (.) operator, which should not have space surrounding it. (System.out.println();)
  6. Unary operators should not be separated by a space. (myGrade++;)

Back to Top