Documentation Standards

All programming projects must be documented. Documentation counts for 10% of the programming project grade. At the top of each file, please include a comment block containing the following information. Note, it does not have to look like this "box" style documentation. However, it should be very readable.
  1. Your Name
  2. Course Name
  3. Project Number and Title
  4. Due Date
  5. Instructor's Name

EXAMPLE:

#********************************************************************
#
# Ima P. Programmer
# Introduction to Computer Programming
# Programming Project #0: Project Title
# January 1, 1970
# Instructor: Michael Scherger
#
#********************************************************************
Each procedure or function should have a documentation "header" that includes the following information
  1. Function or Procedure Name
  2. A Brief Description of the Function or Procedure
  3. Value Parameter Data Dictionary
  4. Reference Parameter Data Dictionary
  5. Local Variable Data Dictionary

EXAMPLE:

#********************************************************************
#
# Ask User To Enter A Number Function
#
# This function prints a question string and prompts the to the user to
# enter a number between low and high-1.  The function returns a valid
# number within the range.
#
# Return Value
# ------------
# response       integer       valid number in range [low, high)
#
# Arguments
# ---------
# question       string        question string to be printed
# low            integer       low value in range
# high           integer       high value in range
#
# Local Variables
# ---------------
# response       integer       valid number in range (also used as a return value)
#
#*******************************************************************
def ask_number(question, low, high):
    """Ask for a number within a range."""

    # local variables
    response = None

    # loop...prompt user and test if response is in the range   
    while response not in range(low, high):
        response = int(raw_input(question))

    # return to calling function
    return response