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
  • describe the purpose, invariants, dependencies, and any other details users of the component should know rather than simply restating its functionality
  • 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
  • all public classes, methods, and constants must be commented using the conventions of Sun's Javadoc
    • first line concisely describes purpose of the package, class, or function
    • after a blank line, additional comments or examples can be included (using HTML tags) as needed
      
• out-of-code documentation
  • README file, included in the top level folder of your project
    • states which class is the main class and the TestSuite class for your project
    • describes resources or other data files needed to run your program
    • notes any known bugs, crashes, or problems with your project's functionality
    • highlights any extra features included in your project
• project artifact
  • describes the high-level design goals of your project
  • explains, in detail, how to add new features to your project
  • justifies major design choices, including trade-offs (i.e., pros and cons), made in your project
  • states any assumptions or decisions made to simplify or resolve ambiguities in your the project's functionality
    

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, 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.

Resources

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