Coding Standards

• General

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

• Code Structure

1. source code goes in src (under trunk)
2. test code goes in test (under trunk)
3. never use wildcards (*) in import statements
4. a class should do one thing and do that one thing well
   • keep them small
   • break up into smaller classes if class becomes unwieldy
5. break up a method into smaller pieces if it gets too long
6. place one blank line between elements in a file (an element is a field, method, or class)
7. one blank line before and after each block of local variables declarations

• 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)
2. do not reveal more than absolutely necessary
3. example: typically constructors can be package-private
   • a public factory method is called by outside world
4. best to start at most restrictive (private) and only increase visibility if there is no choice
5. generally, fields should be private
   • write access methods for those that need to be revealed
6. 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
2. class and interface names start with uppercase letters and are written in CamelCase
3. method and variable names generally start with lower case letters and are written using camelCase
   • exception: "constants" generally all caps:
     • public final static int MEM_BOUND = 2060;
   • exception: names of enum elements:
     • public enum Result {YES, NO, MAYBE};
4. avoid abbreviations in identifiers
   • For example "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
2. See ​http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
3. every element (method, field, class, interface, ...) has a javadoc
4. javadocs should explain
   • ask yourself would someone who has never seen this code before be able to read this and understand what it does?
5. 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
6. javadocs for interface methods should not reveal implementation details
7. 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
8. 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)
9. packages should have a javadoc in a file package-info.java