How Coding Conventions Inform Design

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

• 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)
• 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
• constructors should initialize all instance variables (even those set to default values)
• 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 may 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)
• 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
• 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
• 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
• use global variables sparingly and, if necessary, separated in their own class
  • (for example, the Singleton Design Pattern)
• use Java API methods and classes rather than write your own implementation whenever possible
• 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.