CSE 160 Python Style Guide
This list is meant to be a reference for the specific style standards the staff of CSE 160 will expect in homework submissions. This is to ensure consistency and fairness in grading.
Remember there are "official" Python Style guidelines you can refer to here for more detail. (Here are also Google's Python guidelines).
Note: Other programming languages (e.g. Java) have different conventions for naming. Use the conventions of the language you are working in.
Variable names in Python should be descriptive, concise, and lowercase, with words separated by underscores. Students shouldn't use single letter names for variables that should really be 'factorial', 'current_sum', or 'reciprocal' but they are fine for loop variables.
- You should use descriptive variable names, such as "factorial" or "current_sum", that describe the value the variable contains.
- In Python, it’s recommended to name variables and functions in a certain way so that other Python programmers can read your code more easily. Here are some examples of variable names: "num_lines", "triangular_number", "running_sum", "my_friends", etc.
- Avoid using python keywords for variable names, such as 'class', 'print', 'import', or 'return'. A list of keywords can be found by typing the following into the Python interpreter
import keyword keyword.kwlist
total height_sum average_weight age
t NumberSum # bad when used as a variable name a_w whats_my_age_again # too verbose, detracts from readability return # python keyword
Function names in Python should be concise, descriptive, and lower-case with words separated by underscores.
read_image(filename) compute_avg(x, y, z) max_neighbors(grid, i, j)
There should be a blank line separating function definitions from other portions of code. Try to minimize blank lines within function definitions, except when separating complex chunks of code/logic to provide readability. Example 2 is
Good Example 1: (blank line separating function bodies)
# other code def read_image(filename): # implementation code # other code
Good Example 2: (blank line separating "complex" chunks of code)
def compute_avg(x, y, z): """ Sums the given numbers and returns the average. """ sum_val = x + y + z # compute and return the average value result = sum_val / 3.0 return result # more code below
Bad Example 1: (not enough blank lines)
# other code def get_height(): # implementation code # other code
Bad Example 2: (too many blank lines)
# other code def get_height(): # implementation code # other implementation code for get_height() # other code
Space Between Operators
Include spaces between mathematical and logical operators and other elements in an expression. Mathematical operators include +, -, /, *, and **. Logical operators include ==, <=, >=, <, and >. Limit space delimiters to 1 space, to avoid unnecessary whitespace. The exception to this is parentheses, which can be directly adjacent to whatever they are enclosing.
x + y (sum ** 2) + 4 * val - 1 x * (4 + 6) b + math.sqrt(4 * max_val)
x+y # not enough spaces (sum**2)+4*val-1 # not enough spaces x * ( 4 + 6 ) # unnecessary spaces around parentheses b + math.sqrt( 4 * max_val) # inconsistent spacing
Note: While in some cases spacing around operators can be left to personal preference, for CSE 160 we will hold your code to this standard as it adds readability to your code.
Space Between Function Names and Parameter List
Avoid adding extra space(s) between a function name and its associated parameter list. For example, you should write, "range(x)" instead of "range (x)" (in other words, do not put a space between ‘range’ and the opening parenthesis). Using the space suggests--incorrectly--that the parenthesis are for grouping an expression, when in fact they are for calling the function.
You should, however, include spaces between individual parameters in the parameter list. This makes your function definitions and calls more readable.
x = math.sqrt(n) range_vals = range(n, 4)
x = math.sqrt (n) # too much space before the parenthesis range_vals = range(n,4) # no spaces between parameters
Limit lines of code/comments to 80 characters to provide readability. If a line extends past this limit, split it onto another line.
Include a header comment at the top of a file to describe what the function of a python program is. Also, long blocks of code with a particular purpose or small bits of particularly complex code should be labeled/explained by a comment (using #) on the preceding line(s).
Each function should contain a docstring (Using """ or ''') describing what the function does and any parameters the function takes and values it returns (if any).
Avoid commenting on information that is unnecessary or obvious to other programmers reading your code (i.e. "initialize variable" or "nested for loop" or "increment count").
Use proper spacing with your comments as well:
#Don't do this # Do this x += 5# This is too close to the code! x += 5 # This is better. x += 5 # Also o.k. x += 5 # Too much!
Avoid unnecessary nested if statements or a series of if statements
Avoid nesting if statements that can be written as one if statement.
if val > 120: print "Green!" elif val > 80: print "Blue!" elif val > 32: print "Red!" else: print "Orange!"
Instead of this:
if val > 120: print "Green!" else: if val > 80: print "Blue!" else: if val > 32: print "Red!" else: print "Orange!"
If the intent is for only one block of code to execute, be sure to use if, elif, else instead of a series of ifs.
if color == 'Red': # code here elif color == 'Green': # code here elif color == 'Blue': # code here elif color == 'Yellow': # code here
Instead of this:
if color == 'Red': # code here if color == 'Green': # code here if color == 'Blue': # code here if color == 'Yellow': # code here
Avoid looping over the same data multiple times in a row
Avoid repeated for loops if you can perform all the operations inside one loop.
for color in color_list: if color == 'Red': # code here elif color == 'Green': # code here elif color == 'Blue': # code here elif color == 'Yellow': # code here
Instead of this:
for color in color_list: if color == 'Red': # code here for color in color_list: if color == 'Green': # code here for color in color_list: if color == 'Blue': # code here for color in color_list: if color == 'Yellow': # code here
- Expressions that evaluate to booleans are great because you don't have to do
any the testing with == and != like you do with other types. Treat them like the
Falsethat they are. Remember that you can use
notto negate a boolean value, as in example 2 below.
If you have a boolean value
if is_sunny: be_happy()
if is_sunny == True: be_happy()
return not is_sunny
return is_sunny == False
if is_sunny: return True else: return False
If you find yourself cutting and pasting lines of code stop and think if this code could be put into a loop or a function instead.
Replicating code from functions that you already wrote
Don't write the same code again if you already have a function that performs that action. Just call the function.
Perhaps two similar but not identical pieces of code can be turned into a function by using parameters.
For homework assignments in CSE 160, avoid using programming concepts not yet presented in lecture.
Lingering Debug Code
Please remove any print statements or unnecessary computations that you added to help debug errors before you turn in your program. Don't just leave unnecessary code commented out. It makes the real code harder to read.
Avoid Global Variables
You should avoid using global variables inside of functions. If you use a variable in a function, you should always pass it as a parameter. Although Python lets you use global variables inside functions, it's very dangerous to do so because it makes it harder to predict what the function will return. Using parameters instead of global variables also helps people calling your function understand what your function does, because they can see what it operates on (what they pass in as arguments).
Unnecessary Use of Parentheses
Avoid using excessive parentheses in your code, when not needed. Too many parentheses detract from readability.
(x + 4) / (6 ** (y ** 2)) # readable
((((x) + (4))) / ((6) ** ((y) ** 2))) # less readable