Coding Standards

CS1021 Related Additions to the Coding Standards

4. Comments

• Interfaces are commented using the same principles as classes.
• @throws is used to annotate any unchecked exceptions that are explicitly throw in a method and all checked exceptions that could be thrown by the method.

7. Design Heuristics

• Inheritance is used only when an is-a relationship exists.
• When available, interface references are preferred over class references.
• Hints to the compiler are used when possible:
  • @Override is used to annotate an overridden method.
  • @FXML is used to annotate any attributes/methods defined in an FXML file.

8. Exceptions

• Caught exceptions have sensible responses in the catch blocks.
• General catch blocks, e.g., (Exception e) are avoided when possible.
• When possible, descriptive text is passed to the constructor when an exception is instantiated.
• Default generated catch block code is changed to something sensible. For example, // TODO or e.printStackTrace() are not acceptable ways to to handle exceptions.

CS1011 Related 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 - All methods are commented using Javadoc style, with the following exceptions:
  • Getters and setters which typically are not commented.
  • The main method is typically only 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.
• 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 Settings -> Settings for New Projects
13. Tools -> Checkstyle
14. Repeat steps 6-11 for this screen