Coding Standard

SE1021 Related Additions to the Coding Standards

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.

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.

SE1011 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. Getters/Accessors and Setters/Mutators
  7. Constructors
  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:

  /*
   * SE1011 - 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 (not required for a class that is the main or driver) and includes @author and @version tags.
• Method comments - public methods are commented using Javadoc style, with the exception of getters and setters which typically are not commented.

  /**
   * 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.
  • 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 SE1011 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.