Cover page images (keyboard)

Documentation

Sue Evans

Adapted from the CS1 Course at Swarthmore College by Lisa Meeden

Hit the space bar for next slide

Learning Outcomes

Documentation

CMSC 201 -
Python Coding Standards

General Comments

Every programming department has a some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than 6 months after having written the original. While no two programming departments standards or conventions may be the same, it is important that all members of the department follow the same standards.
Neatness counts ! ! !
At UMBC, the following standards have been created and are followed in CMSC 201.

Part of every project grade is based upon how well these standards are followed.

It is your responsiblity to understand these standards. If you have any questions, ask your instructor, any of the TAs or the Help Center.

Naming Conventions

Use of Whitespace

The prudent use of whitespace (blank lines as well as space) goes a long way to making your program readable.

Work within an 80-character screen

Whether writing code or having your program produce output, you should try to fit it into an 80-character wide screen whenever possible. You should never let a print statement wrap down to the beginning of the next line, since it obscures the indentation. Break these statements up into multiple print statements. Occasionally there may be a calculation that's too long to fit, so sometimes wrapping is unavoidable.

break & continue

Using break and continue is not allowed in any of your code for this class. Using these statements damages the readability of your code. Readability is a quality necessary for easy code maintenance.

Comments

Comments are the programmers main source of documentation. Comments for files, functions and code are described below.

File Header Comments

Every file should contain an opening comment describing the contents of the file and other pertinent information. This "file header comment" MUST include the following information.

  1. The file name
  2. Your name
  3. The date the file was created
  4. Your section number
  5. Your UMBC e-mail address
  6. A description of the contents of the file

For example:


# File:    hw3.py
# Author:  Sue Evans
# Date:    9/22/09
# Section: 4
# E-mail:  bogar@cs.umbc.edu 
# Description:
# This file contains python code that will decode an English 
# message that was encoded using a Caesar cypher with a fixed 
# rotation length.  It  makes use of letter frequencies in
# the English language to determine the rotation length.

Function Header Comments

EACH FUNCTION must have a header comment that includes the following:

  1. function name
  2. a description of what the function does
  3. a description of the function's inputs
  4. a description of the function's outputs
  5. side effect of the function (if any -- this should be rare)

For example:

# findCircleArea() calculates the area of a circle with the radius passed in
# Input:  the circle's radius
# Output: the circle's area

In-Line Comments

Greeting the User

Every program should begin by explaining to the user what the program does. Once you have learned to write functions, you should always have a function called printGreeting() that accomplishes this purpose.

Use of Constants

To improve readability, you should use constants whenever you are dealing with values. Your code shouldn't have any "magic numbers", numbers whose meaning is unknown. This means numbers used in calculations other than 0 or 1. Here's an example of code using a magic number, .06:

total = subtotal + subtotal * .06

.06 is a magic number. Why? What is it? We don't know. So, at the very least this line of code would require a comment. However, if we use a constant, the number's meaning becomes obvious, the code more readable, and no comment is required. Constants are always placed near the top of the program so that if their value ever changes they are easy to locate to modify and so that they stay in scope throughout the program.

TAX_RATE = .06

... (lots of code goes here)

total = subtotal + subtotal * TAX_RATE

... (other code goes here)

print "Maryland has a sales tax rate of %.2f percent" % (100 * TAX_RATE)

A Sample Program


# Filename:    format2.py
# Written by:  Sue Evans 
# Date:        7/29/09
# Section:     All
# Email:       bogar@cs.umbc.edu
#
# This program illustrates the use of the if-else 
# structure working with strings that can contain 
# any of the printable characters.  It counts the 
# number of letters, digits, spaces and other
# characters in the input string.

def main():

    import string

    # give an explanation of the program
    print
    print "This program counts the letters, digits,"
    print "spaces and other characters in a message."
    print
    
    # initialize the counters
    letters = 0
    digits = 0
    spaces = 0
    others = 0

    # get a string from the user
    message = raw_input("Enter your message : ")

    # change the message to have only upper case letters
    allCaps = string.upper(message)

    # loop over the string counting character types
    for char in allCaps :

        # get ASCII value of char
        value = ord(char)
        
        # if char is a letter, increment letters
        if value >= 65 and value <= 90 :
            letters = letters + 1
        # if it's a digit, increment digits
        elif value >= 48 and value <= 57 :
            digits = digits + 1
        # if it's a space, increment spaces 
        elif value == 32 : 
            spaces = spaces + 1 
        # if none of the above, increment others   
        else : 
            others = others + 1 
            
    # calculate total number of characters 
    total = letters + digits + spaces + others 
    
    # print the formatted results
    print
    print "Letters : %3d" % (letters)
    print " Digits : %3d" % (digits)
    print " Spaces : %3d" % (spaces)
    print "  Other : %3d" % (others)
    print "          ---"
    print "  Total :%4d" % (total)
    print
    

main() 

A Program Written to 201 Standards


# Filename:    format2.py
# Written by:  Sue Evans 
# Date:        7/29/09
# Section:     All
# Email:       bogar@cs.umbc.edu
#
# This program illustrates the use of the if-else 
# structure working with strings that can contain 
# any of the printable characters.  It counts the 
# number of letters, digits, spaces and other
# characters in the input string.

def main():

    import string

    # set constants
    A = 65
    Z = 90
    ZERO = 48
    NINE = 57
    SPACE = 32

    # give an explanation of the program
    print
    print "This program counts the letters, digits,"
    print "spaces and other characters in a message."
    print
    
    # initialize the counters
    letters = 0
    digits = 0
    spaces = 0
    others = 0

    # get a string from the user
    message = raw_input("Enter your message : ")

    # change the message to have only upper case letters
    allCaps = string.upper(message)

    # loop over the string counting character types
    for char in allCaps :

        # get ASCII value of char
        value = ord(char)
        
        #increment appropriate counter
        if value >= A and value <= Z :
            letters = letters + 1
        elif value >= ZERO and value <= NINE :
            digits = digits + 1
        elif value == SPACE : 
            spaces = spaces + 1 
        else : 
            others = others + 1 
            
    # calculate total number of characters 
    total = letters + digits + spaces + others 
    
    # print the formatted results
    print
    print "Letters : %3d" % (letters)
    print " Digits : %3d" % (digits)
    print " Spaces : %3d" % (spaces)
    print "  Other : %3d" % (others)
    print "          ---"
    print "  Total :%4d" % (total)
    print
    

main() 


linuxserver1.cs.umbc.edu[135] python format2.py

This program counts the letters, digits,
spaces and other characters in a message.

Enter your message : It's the 1000th time !!!!!

Letters :  12
 Digits :   4
 Spaces :   4
  Other :   6
          ---
  Total :  26

linuxserver1.cs.umbc.edu[136]