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.
- Your Name
- Course Name
- Project Number and Title
- Due Date
- 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
- Function or Procedure Name
- A Brief Description of the Function or Procedure
- Value Parameter Data Dictionary
- Reference Parameter Data Dictionary
- 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