CMSC 201 - Python Coding Standards
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.
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 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.
# File: hw3.py # Author: Sue Evans # Date: 9/22/09 # Section: 4 # E-mail: firstname.lastname@example.org # 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:
# findCircleArea() calculates the area of a circle with the radius passed in # Input: the circle's radius # Output: the circle's area
# 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
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. Here's an example:
total = subtotal + subtotal * .06
.06 is a magic number. 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 typically 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)
Last Modified :Monday, 24-Oct-2011 19:54:29 EDT
|Adapted from UMBC CSHC's webpage design|