== Coding Standards ==

=== General ===

1. All code should compile without errors or warnings;
1. Eclipse should indicate no warnings.

=== Code Structure and Formatting ===

1. source code goes in the directory `src`
1. test code goes in one of the `test` directories:
 * `test/regress` : regression tests.  These are short tests that are expected to always pass.   When a developer changes something, she should be able to quickly run the regression tests to determine if the change "broke" anything.  In general, merges into the trunk will be rejected if they break any regression test.
 * `test/dev` : development tests.   These are tests for newly discovered defects or for new features under development.   At any time, they will not necessarily all pass.  However, the goal should be to get them to pass.   Once a development test is passing, it should be moved to `test/regress` and becomes a regression test, or to `test/big`.
 * `test/big` : these are tests that should pass, but take too long or consume too much memory to be useful as regression tests.
1. never use wildcards (*) in import statements
1. a class should do one thing and do that one thing well
 * keep them small
 * break up into smaller classes if class becomes unwieldy
1. break up a method into smaller pieces if it gets too long
1. place one blank line between elements in a file (an element is a field, method, or class)
1. one blank line before and after each block of  local variables declarations
1. apply the Eclipse formatter (Source->Format) to all source files

=== Visibility ===
1. think carefully about the visibility level for each element, i.e., whether to make the element public (visible to all), protected (visible to package and sub-classes), package-private (visible to package, the default in Java), or private (visible to same class only)
1. do not reveal more than absolutely necessary
1. example: typically constructors can be package-private
 * a public factory method is called by outside world
1. best to start at most restrictive (private) and only increase visibility if there is no choice
1. generally, fields should be private
  * write access methods for those that need to be revealed
1. methods declared in (Java) interfaces must be public so don't declare them to be (i.e., leave out the public)

=== Names ===
1. generally, package names are all lower case letters
 * exception: `IF`
1. class and interface names start with uppercase letters and are written in `CamelCase`
1. method and variable names generally start with lower case letters and are written using `camelCase`
 * exception: "constants" are generally all caps:
   - `public final static int MEM_BOUND = 2060;`
   - exception: names of enum elements:
      - `public enum Result {YES, NO, MAYBE};`
1. avoid abbreviations in identifiers
  * for example  use `expression`, not `expr`
  * use meaningful names for identifiers that explain their purpose

=== Documentation ===
1. See [http://docs.oracle.com/javase/7/docs/api/] for good examples of javadocs
1. See [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html]
1. every element (method, field, class, interface, ...) has a javadoc
1. javadocs should ''explain''
 * ask yourself ''would someone who has never seen this code before be able to read this and understand what it does?''
1. tags
    - which tags occur in javadocs is not nearly as important as the clarity and completeness of the explanation
    - do not include a tag with no information associated to it
    - do include an {{{@author}}} tag for each file
    - do include an {{{@exception}}} tag for each exception (including runtime exceptions) that could be thrown
1. javadocs for interface methods should not reveal implementation details
1. javadocs for methods in a class that implement a method declared in an interface can simply refer to the interface javadoc and add any additional information specific to that implementation; do not copy and paste the interface javadoc
1. method javadocs should list the pre-conditions and post-conditions for the method
    - a pre-condition is a condition the program state should satisfy when the method is called.  This is typically a condition on the parameters to the method, e.g., {{{N>0}}}.
    - a post-condition is a guarantee: it states a condition the program state must satisfy when the method returns (assuming the method was called in a way that satisfied the pre-condition)
1. packages should have a javadoc in a file {{{package-info.java}}}