Learning Outcomes

• An understanding of what's meant by documentation
• Become familiar with the 201 documentation and coding standards
• Understand that the user should always be told about the program before it runs.
• Understand that using constants not only allows for easy modification, but also increases readability without requiring comments.

Documentation

• For this course, documentation will primarily consist of the file header comments, function header comments and in-line comments that you'll need to use in your .py files.
• In practice, documentation certainly consists of comments within the code, but much more. Some different types of documentation are :
  • requirements documents
  • system design documents
  • user interface design documents
  • use case documents
  • code inspection reports
  • code test reports
  • administrator's manuals
  • user's manuals
  You'll become acquainted with these in CMSC 345, our Software Engineering course.

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 meaningful variable names ! !
  For example, if your program needs a variable to represent the radius of a circle, call it 'radius', NOT 'r' and NOT 'rad'. The use of single letter variables is forbidden.
  The use of obvious, common, meaningful abbreviations is permitted. For example, 'number' can be abbreviated as 'num' as in 'numStudents'.
• Begin variable and function names with lowercase letters
• Constant names should be in all caps, i.e. EURO_TO_USD = 1.34894
• Do not use global variables
• Separate "words" within identifiers with underscores or mixed upper and lowercase. Example: grandTotal or grand_total
• Be consistent! If you choose to use mixed case, always use mixed case.

Use of Whitespace

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

• Use blank lines to separate major parts of a function.
• DO NOT use tabs (unless your editor changes TABs to 4 SPACEs). Emacs and xemacs does this for you.
• Use 4 spaces for each level of indentation
• Use spaces around all operators. For example, write x = y + 5, NOT x=y+5
• Using the emacs or xemacs editor will automatically indent your code appropriately.

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

• "In-line" comments are used to clarify what your code does, NOT how it does it.
• Well structured code will be broken into logical sections that perform a simple task. Each of these sections of code (typically starting with an 'if' statement, or a loop should be documented.
• Any confusing-looking code should also be commented.
• Do not comment every line of code. Trivial comments (# increment x ) are worse than no comments at all.
• An in-line comment appears above the code to which it applies and is indented to the same level as the code.
  For example:

      # check every member of a list 
      for num in numList :
     
          # if it's odd, print it, if even, do nothing
          if num % 2 == 1 :
              print num
  

• Endline comments are not allowed :

      for num in numList :        # check every member of a list 
  

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() 

• Let's run it :

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]