Coding Standard

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".

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. Other 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

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.

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.

  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.
  • 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.");
        }
    }
    

  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.