Java Coding Standards

These are Java's official code conventions, which we will be following for this course:

• Code Conventions for the Java Programming Language

It is a relatively short document and you should read through it at least once.

Below is a reminder checklist of the most important things to remember for this class:

Identifiers

• Use descriptive and relevant names for all variables, methods, classes, interfaces, and packages.
• For all identifiers (except constants), use "camel notation": capitalize the first letter of each internal word that makes up the variable name. Do not use underscores. (For constants, use all uppercase letters and underscores between words.)
• Avoid single letter names (except when they are clear and of limited scope, such as with loop counters).
• Variable names should begin with a lowercase letter.
• Classes names should be nouns and begin with an uppercase letter.
• Method names should be verbs (or begin with a verb) and begin with a lowercase letter.

Braces

• Opening curly braces ({) should be placed at the end of the line that starts the code block. (Alternately, the opening brace may be placed alone on the next line, indented even with the beginning of the previous line.)
• Closing curly braces (}) should be placed on their own line and indented even with the line that starts the code block.
• Always use braces for if, while, for, and other control structures.

  Example:

  public class Example {
    public static void main(String[] args) {
      if (args.length == 0) {
        System.out.println("You did not provide any command line arguments.");
      }
    }
  }
  

White space

• Indent all code blocks. That is, after an opening {, indent all lines until the matching closing }.
• Indent 2 spaces, 4 spaces, or use the tab key. Pick one of these and be consistent throughout your code. Do not mix tabs and spaces in your indenting!
• Put spaces between binary operators, such as +, *, &&, etc.
• Keep your lines to 80 characters or less in length.
• Put a blank line between logically related chunks of code. Put one or two blank lines between method declarations.

Documentation

• Document each class with a /** javadoc */ block. Describe the function or purpose of the class in one or two sentences. (The assignment number alone does not count as documentation.) Include your name as author using the @author tag.
• Any import statements go before documentation for the class.
• Document each method with a /** javadoc */ block. The documentation should describe simply what the method does, and not how it was implemented or where it is called from. In your documentation, remember to document the parameters, return values, exceptions thrown, and any side-effects (such as instance or global variables affected, output generated, etc.). Documentation should add information beyond what is already obvious from the method signature itself.
• You do not need to document simple accessor and mutator methods ("getters and setters"). You do not need to document the main method if it is the only method in the class (since your class documentation should be sufficient in this case).
• To learn more about the fine art of documenting Java code, see: How to Write JavaDoc Comments.

Comments

• Within your methods, you should comment your code. Unless the code is particularly complicated, a //comment for every logical chunk (usually 3 to 7 lines) is sufficient.
• //comments go on the line before the code they refer to, or else on the same line after the code. If on its own line, indent the //comment even with the code it refers to.
• Do not comment on simple or obvious features of the language.

  An example of excessive and obvious commenting:

    //declare num and assign 4 to it
    int num = 4;
    //compare num to 4
    if (num == 4) {
      //print "num is still 4" to the screen
      System.out.println("num is still 4.");
    }
  

Error messages

• If your program detects and reports an error to do with user input, the error message should be as specific and helpful as possible, without being overly technical.
• Error messages should never be abrasive, insulting, or vulgar.

More Examples

For more examples and counter-examples, see:

• ICS Java Coding Standards