Documentation Requirements

All program documentation must contain the following elements:
  1. Header documentation at the beginning of each file that contains:
    1. the name of the programmer
    2. the date
    3. a description of the purpose of the program or class that is defined in the file
    4. a clear description of any input expected (especially the format of a file)

  2. Meaningful variable, constant, and function names with comments describing the role of each variable.

  3. Use of constants for most literal values.

  4. Documentation before each function or method that contains the following:
    1. A brief description of what the function does
    2. Clear and precise preconditions for the function or method including
      1. the state of each parameter before the function or method is invoked
      2. the state of the object (if the function or method is part of a class) before the method is invoked
    3. Clear and precise postconditions for the function or method including
      1. the state of each parameter when the function or method returns
      2. the state of the object (if applicable) when the function or method returns
      3. the state of the return value (if there is one)

  5. Internal comments in appropriate places indicating the state of relevant variables or describing what the code does.