Coding Standards

1. Source Files - Filename matches Class name

• File name - the source file name consists of the case-sensitive name of the top-level class the file contains.
• File extension - the source file extension is ".java".

2. Source File Structure

• A source file maintains the following order:
  1. File header
  2. Package statement
  3. Import statement(s)
  4. Exactly one top-level class
  5. Attributes
  6. Constructor(s)
  7. Getters/Accessors and Setters/Mutators
  8. Public methods
  9. Helper methods
• File headers are a comment block consisting of the following:
  1. Course
  2. Section
  3. Quarter
  4. Academic Year
  5. Assignment or lab name or number
  6. Student name
  7. The date the file was first created
• An example of a file header is:

/*
 * Course: CS1011 - 021
 * Fall 2015
 * Lab 2 - My First Program
 * Name: Brad Dennis
 * Created: 10/13/2015
 */

• There is a line space above comments in code that are not inline

3. Special Characters - Never type a literal tab

• "\t" is used rather than a literal tab character.
• Four spaces are used instead of a tab character for indentation.

4. Comments

• Class comments - each class is commented using Javadoc style.
  • The comment contains a brief description of the class.
  • The class comment for the class containing the main method describes the entire program.
• Method comments - other than the exceptions below, all methods are commented using Javadoc style
  • However, getters and setters which typically are not commented.
  • The main method is documented if command line arguments are used.

/**
 * This method prints out "Hello" to the person given and
 * returns the number of letters in the person's name.
 *
 * @param name The person to who to say hello.
 * @return The number of characters in the person's name.
 */

• Attribute comments - public attributes are commented using Javadoc style; private attributes may be commented.
• Inline comments - used when necessary. These are used when the meaning of the code is not obvious from reading the method heading text or to document key design decisions, algorithms, or tasks.
• Self-documenting code:
  • Meaningful names are used for all variables, parameters, classes, and methods. Names consist of complete words where practical.
  • Named constants are used instead of numeric literals.
  • Boolean variables and methods are not compared to boolean literals.
  • Loop exit/continue conditions are clearly specified in the loop's condition statement. For example, instead of this

while(isDone==false) {
    // ...
    if(str.length()>0 && str.charAt(0)=='A') {
        isDone = true;
    } 
}

write

while(str.length()==0 || str.charAt(0)!='A') {
    // ...
}

• Flower-boxes or other designs - comments are not enclosed in boxes drawn with asterisks or other characters.

5. Formatting

• Variable and Method names - the first letter is lowercase, the first letter of each subsequent word in the name is capitalized, e.g., lowerCamelCase.
• Class names - Each word is capitalized, e.g., UpperCamelCase.
• Constants - the entire word is capitalized; multiple words are separated by underscores, e.g., DEFAULT_LINE_LENGTH.
• Each variable declaration and initialization is placed on a separate line.
• Braces
  • The body of an if, while, do-while, and for statement is surrounded with curly braces.
  • The open brace is placed at the end of the line before the start of the code block. The close brace is placed on its own line, indented to match the beginning of the line containing the open brace. (Egyptian Braces)
• Indentation - code is indented four spaces for each level of braces.
• Continued lines - each line of a continuation is formatted in a logical and understandable manner.
• Column Limit - no line of code (including comments) contains more than 100 characters.
• An example of a properly formatted code snippet is shown below:

public void someMethod(int argumentOne) {
    if(argumentOne<=0) {
        doSomething();
    } else {
        doSomethingElse("Perhaps the best way to deal with " + argumentOne + 
                        " pieces of pizza is to eat them.");
    }
}

6. Rules of Programming Discourse

• The names of variables and methods reflect their purpose.
• Magic numbers should not be used. (updated fall 2021)
• Code that is not going to be executed is not included.
• A tested condition must have the potential of evaluating to true or false.
• A variable that is initialized by an assignment is subsequently updated with assignment statements.
• An if() is used to execute code zero or one times whereas for() and while() are used to execute code zero or more times.

7. Design Heuristics

• Don't Repeat Yourself (DRY) - Duplicated code with the same structure in more than one place is avoided.
• Avoid Long Methods - Long methods are avoided by logically breaking the method into multiple smaller methods.
• Minimize Scope - The scope of variables is limited as much as possible. Where possible, the following order of preference is used: local variable, private instance variable, protected instance variable, private class variable, public instance variable, public class variable.
• Hints to the compiler are used when possible:
  • Variables are declared final when their value should not change.
  • Generics are specified whenever possible.

Example Class

A complete class example, is provided in the Complex class implementation in the CS1011 classes tutorial.

Acknowledgement

This coding standard was developed by the MSOE software engineering faculty and is based upon Java Style Guide published by Google and other sources.

CheckStyle

The CheckStyle plugin should be used to help ensure consistency with the coding standard. Here are the steps for installing the plugin in IntelliJ:

1. File -> Settings -> Plugins
2. Search for "CheckStyle" and click "Search in repositories", if shown
3. Select CheckStyle-IDEA and click "Install"
4. Restart IntelliJ
5. File -> Settings -> Tools -> Checkstyle**
6. Click on + to add a Configuration File
7. Enter MSOE for the Description
8. Select "Use a Checkstyle file accessible via HTTP" and enter https://faculty-web.msoe.edu/jones/MSOE_checkStyle.xml
9. Click Next and then Finish
10. Click the "Treat Checkstyle errors as warnings" box
11. Ensure that the checkbox for MSOE is selected and click OK
12. File -> New Project Setup -> Settings for New Projects
13. Tools -> Checkstyle
14. Repeat steps 6-11 for this screen