How Coding Conventions Inform Design

Your project's code must adhere to the following code-level design conventions:

0. code should follow an internally consistent set of coding conventions with regard to
   • indentation, using Spaces Only, NOT Tabs
   • brace placement
   • capitalization
   • instance variable and constructor placement (e.g., at the top of the class)
   • naming conventions (e.g., all instance variables start with the prefix "my")
(for example, the conventions here are given by Sun for Java code)
1. carefully choose the names within your program since they are critcial to understanding your code
   • use meaningful, non-abbreviated, names for classes, methods, and variables that reflect their purpose rather than their type
   • use methods with meaningful names rather than inline code that needs to be commented
   • use constants rather than literal values for all values used multiple times or in program logic
   • use resource values rather than literal values for all text that will be displayed to a user
2. variables should be declared as close to where they are used as possible
   • local variables should be declared when they can be initialized
   • private methods should use parameters and return values to communicate information rather than instance variables
   • super-classes should not contain instance variables specific to only some sub-classes
   • use global variables sparingly and, if necessary, separated in their own class
     • (for example, the Singleton Design Pattern)
3. encapsulate implementation decisions by focusing on the behavior of your class first
   • instance variables should be only private or protected (with private being much preferred)
     • protected instance variables should be commented extensively to justify this decision
     • no instance variables should be public (get/set methods should also include comments that justify their existence)
   • classes should minimize their number of get/set methods (and never have only those methods)
     • get methods should try to protect the data they give out (e.g., by returning an unmodifiable version of a collection)
     • set methods should try to validate the data they receive (e.g., protect against null or validate class invariants)
       • if a set method does not protect against null assignment, then all uses of that value in the class must be checked before use
     • classes must provide some behavior within the program (i.e., they cannot simply consist of get/set methods)
   • declared types should be as general as possible (i.e., prefer Iterator to Collection to List to ArrayList)
4. do not repeat yourself by copying and pasting code, either exactly, in logical structure, or value access
   • conditional chains that distinguish between a few different kinds of behavior should be replaced by polymorphism
   • complex logic that creates sub-classes should be replaced by the Factory Design Pattern and/or data structures when possible
   • hard coded one-at-time code should be avoided (use data driven automated code via data structures or files)
   • this is especially true within constructors and subclasses
     • constructors should initialize all instance variables (even those set to default values)
     • sub-classes should contain as little code as possible to differentiate them from their super-class, superclasses should support overriding small specific methods
       (for example, the Template Method Design Pattern)
       • sub-classes should use the @Override annotation for all methods being overridden
5. use Java API methods and classes rather than write your own implementation whenever possible
6. your code should contain no warnings from the compiler

If you feel you must violate one of the conventions, you must document the reason within your code.