Java Style and Documentation Guide

In your submitted work, always follow the conventions that we practice in class for making your code look as neat and professional as possible. The easier to read and understand your work is, the higher your grade is likely to be. Some of the most important conventions, as well as documentation requirements, are listed below.

A.   Naming

  1. An identifier name should describe its purpose, except for routine local variables whose purpose is obvious (such as loop counters).
  2. Use lowercase letters in the names of variables and methods, except to separate words; e.g., numberOfDays or getName.
  3. Class names are always capitalized.
  4. Always use constants instead of magic numbers (except for zeros and ones, which are ok to embed in code).
  5. Constant names are UPPERCASE, with an UNDER_SCORE to separate words.

B.   Indentation and Whitespace

  1. Use 3 or 4 spaces for each level of indentation (you can set the tab spacing in your editor).
  2. Leave a space before and after every binary operator.
  3. Leave a blank line after every method.
  4. Use blank lines to separate parts of a method that are logically distinct.
  5. Avoid code drift: each line should be at most 80 characters long.
  6. Indent all statements appearing within a block to indicate flow of control.
  7. Line up closing braces of blocks with the keyword owning the block.
  8. There should be no more than two consecutive blank lines.

C.   Documentation

  1. Each class must begin with a proper Javadoc comment including the purpose of the file and the author's name.
  2. Each method must be preceded by a proper Javadoc comment with param and return tags as needed.
  3. Within a method, comments are needed to explain any code whose purpose is not obvious.
  4. Write a comment to explain the purpose of a variable unless the purpose is obvious from the name.
  5. Document all known errors and deficiencies. This makes your code look more professional. It is also a form of intellectual honesty.

D.   Miscellaneous

  1. Remove useless IDE-generated comments.
  2. Remove typos and grammatical errors from output and documentation. These give the code the appearance of a cheap and flimsy product.
  3. Methods should not be longer than about 30 lines, and usually not longer than 20. Implement utility methods for subtasks.