Code Design Conventions

Each project you submit must include the following documentation:

• your name(s) on all files on which you worked
• all files must include a comment at the top that describes its purpose
• in-code comments
  • superclasses, interfaces, and modules should be heavily commented to describe their role in the program, especially abstract methods
  • subclasses that are short and follow a standard pattern can be lightly commented
  • inline comments should be kept to a minimum, because the code should be made to be readable on its own
    • code hacks, or other non-standard code, should be factored into a separate method and commented extensively
  (comments should describe the purpose, invariants, dependencies, and any other details users of the component should know rather than simply restating its functionality)
• all public classes, methods, and constants must be commented using the conventions of Sun's Javadoc
  
• out-of-code documentation that describes any assumptions or decisions you made to simplify or resolve ambiguities about the program's functionality
  (this can be included in the README file submitted with your project)
• out-of-code documentation that states which class is the main class and the TestSuite class for your project
  (this can be included in the README file submitted with your project)
• for team projects, a current version of the project's design documentation
  

Additionally, 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
  • brace placement (or spacing)
  • capitalization
  • instance variable and constructor placement
  • 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 code written inline
• use constants rather than literal values for those values used multiple times or in program logic
• use resource values rather than literal values for text that will be displayed to the user
• constructors should initialize all instance variables
• 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
  • set methods should try to validate the data they receive
  • 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
  • for example, local variables should be declared when they can be initialized
  • for example, classes should not collect variables that are expected to cover all possibilities later on (i.e., only in sub-classes or in variants of an algorithm)
• 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, see 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 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, see 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.

Resources

• Code Smells Taxonomy
• Design Principles
• Refactoring Home
• Design Heuristics