CS240 Python Coding Conventions
For this course we will primarily follow the PEP 8 Style Guide for Python Code. This is the style guide that describes the coding standards for code to be included in the Python standard library. I encourage you to read that entire document, but you are only responsible for the boxed (and edited) excerpts included on this page. I also recommend taking a look at Google Python Style Guide. Again, you are not responsible for that material, but it has some good advice for writing well organized Python code.Code lay-out
Executable programs for this course should define a main
function that is called from within a conditional block like the
following:
if __name__ == "__main__":
main()
Under no circumstances should your modules include function calls that
occur unconditionally. Such calls interfere with the
use of PyDoc, and make it difficult for me to use testing code that
imports your module.
PEP 8:
Indentation
Use 4 spaces per indentation level.
Tabs or Spaces?
Never mix tabs and spaces.
For new projects, spaces-only are strongly recommended over tabs. Most
editors have features that make this easy to do.
Maximum Line Length
Limit all lines to a maximum of 79 characters.
The preferred way of wrapping long lines is by using Python's implied line
continuation inside parentheses, brackets and braces. Long lines can be
broken over multiple lines by wrapping expressions in parentheses. These
should be used in preference to using a backslash for line continuation.
Make sure to indent the continued line appropriately. The preferred place
to break around a binary operator is *after* the operator, not before it.
Some examples:
class Rectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if (width == 0 and height == 0 and
color == 'red' and emphasis == 'strong' or
highlight > 100):
raise ValueError("sorry, you lose")
if width == 0 and height == 0 and (color == 'red' or
emphasis is None):
raise ValueError("I don't think so -- values are %s, %s" %
(width, height))
Blob.__init__(self, width, height,
color, emphasis, highlight)
Imports
PEP 8:
- Imports should usually be on separate lines, e.g.:
Yes: import os
import sys
No: import sys, os
it's okay to say this though:
from subprocess import Popen, PIPE
- Imports are always put at the top of the file, just after any module
comments and docstrings, and before module globals and constants.
Whitespace in Expressions and Statements
PEP 8:
Avoid extraneous whitespace in the following situations:
- Immediately inside parentheses, brackets or braces.
Yes: spam(ham[1], {eggs: 2})
No: spam( ham[ 1 ], { eggs: 2 } )
- Immediately before a comma, semicolon, or colon:
Yes: if x == 4: print x, y; x, y = y, x
No: if x == 4 : print x , y ; x , y = y , x
- Immediately before the open parenthesis that starts the argument
list of a function call:
Yes: spam(1)
No: spam (1)
- Immediately before the open parenthesis that starts an indexing or
slicing:
Yes: dict['key'] = list[index]
No: dict ['key'] = list [index]
- More than one space around an assignment (or other) operator to
align it with another.
Yes:
x = 1
y = 2
long_variable = 3
No:
x = 1
y = 2
long_variable = 3
Other Recommendations
- Always surround these binary operators with a single space on
either side: assignment (=), augmented assignment (+=, -= etc.),
comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not),
Booleans (and, or, not).
- Use spaces around arithmetic operators:
Yes:
i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
No:
i=i+1
submitted +=1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
- Don't use spaces around the '=' sign when used to indicate a
keyword argument or a default parameter value.
Yes:
def complex(real, imag=0.0):
return magic(r=real, i=imag)
No:
def complex(real, imag = 0.0):
return magic(r = real, i = imag)
- Compound statements (multiple statements on the same line) are
generally discouraged.
Yes:
if foo == 'blah':
do_blah_thing()
do_one()
do_two()
do_three()
Rather not:
if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()
- While sometimes it's okay to put an if/for/while with a small
body on the same line, never do this for multi-clause
statements. Also avoid folding such long lines!
Rather not:
if foo == 'blah': do_blah_thing()
for x in lst: total += x
while t < 10: t = delay()
Definitely not:
if foo == 'blah': do_blah_thing()
else: do_non_blah_thing()
try: something()
finally: cleanup()
do_one(); do_two(); do_three(long, argument,
list, like, this)
if foo == 'blah': one(); two(); three()
Comments
The point of comments is to clarify code that might otherwise be difficult for the reader to follow. Well organized Python code with informative variable names should require very few comments inside the bodies of functions and methods.
PEP 8:
Comments that contradict the code are worse than no comments. Always make
a priority of keeping the comments up-to-date when the code changes!
Comments should be complete sentences. If a comment is a phrase or
sentence, its first word should be capitalized, unless it is an identifier
that begins with a lower case letter (never alter the case of
identifiers!).
If a comment is short, the period at the end can be omitted. Block
comments generally consist of one or more paragraphs built out of complete
sentences, and each sentence should end in a period.
You should use two spaces after a sentence-ending period.
When writing English, Strunk and White apply.
Block Comments
Block comments generally apply to some (or all) code that follows them,
and are indented to the same level as that code. Each line of a block
comment starts with a # and a single space (unless it is indented text
inside the comment).
Paragraphs inside a block comment are separated by a line containing a
single #.
Inline Comments
Use inline comments sparingly.
An inline comment is a comment on the same line as a statement. Inline
comments should be separated by at least two spaces from the statement.
They should start with a # and a single space.
Inline comments are unnecessary and in fact distracting if they state
the obvious. Don't do this:
x = x + 1 # Increment x
But sometimes, this is useful:
x = x + 1 # Compensate for border
Documentation Strings
PEP 8:
Conventions for writing good documentation strings (a.k.a. "docstrings")
are immortalized in PEP 257 [3].
- Write docstrings for all public modules, functions, classes, and
methods. Docstrings are not necessary for non-public methods, but you
should have a comment that describes what the method does. This comment
should appear after the "def" line.
- PEP 257 describes good docstring conventions. Note that most
importantly, the """ that ends a multiline docstring should be on a line
by itself, and preferably preceded by a blank line, e.g.:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
- For one liner docstrings, it's okay to keep the closing """ on the same
line.
Naming Conventions
Selecting informative names is one of the most important steps in writing readable, maintainable, and correct code. Variable names should generally be nouns, and should clearly describe what the variable is intended to contain. Single letter variable are almost never acceptable, with exception of loop index variables. It is usually a good idea to use plural nouns for variables that will contain collections, and singular nouns for variables that will contain individual objects.
Variable names should balance clarity with brevity. The
name person is better
than currentPersonObject. However, per is
worse than either (percentage? person?, permitted?).
Function and method names should typically be verbs and should describe what the function or method is intended to accomplish.
Avoid selecting place-holder names with the intention of replacing them later. If you aren't sure what the variable or function should be named, that's often an indication that you don't have a clear idea of what the variable will hold or what the function should accomplish. Taking the time to figure out an appropriate name will clarify your thinking.
PEP 8 (CS240 changes in red):
Naming Conventions
Names to Avoid
Never use the characters `l' (lowercase letter el), `O' (uppercase
letter oh), or `I' (uppercase letter eye) as single character variable
names.
In some fonts, these characters are indistinguishable from the numerals
one and zero. When tempted to use `l', use `L' instead.
Package and Module Names
Modules should have short, all-lowercase names. Underscores can be used
in the module name if it improves readability. Python packages should
also have short, all-lowercase names, although the use of underscores is
discouraged.
Class Names
Almost without exception, class names use the CapWords convention.
Classes for internal use have a leading underscore in addition.
Exception Names
Because exceptions should be classes, the class naming convention
applies here. However, you should use the suffix "Error" on your
exception names (if the exception actually is an error).
Function Names
Function names should be mixedCase.
Method Names and Instance Variables
Use the function naming rules.
Use one leading underscore only for non-public methods and instance
variables.
Constants
Constants are usually defined on a module level and written in all
capital letters with underscores separating words. Examples include
MAX_OVERFLOW and TOTAL.
Designing for inheritance
Always decide whether a class's methods and instance variables
(collectively: "attributes") should be public or non-public. If in
doubt, choose non-public; it's easier to make it public later than to
make a public attribute non-public.
Public attributes are those that you expect unrelated clients of your
class to use, with your commitment to avoid backward incompatible
changes. Non-public attributes are those that are not intended to be
used by third parties; you make no guarantees that non-public attributes
won't change or even be removed.
With this in mind, here are the Pythonic guidelines:
- Public attributes should have no leading underscores.
- For simple public data attributes, it is best to expose just the
attribute name, without complicated accessor/mutator methods. Keep in
mind that Python provides an easy path to future enhancement, should
you find that a simple data attribute needs to grow functional
behavior. In that case, use properties to hide functional
implementation behind simple data attribute access syntax.
Note 1: Properties only work on new-style classes.
Programming Recommendations
PEP 8:
- Don't compare boolean values to True or False using ==
Yes: if greeting:
No: if greeting == True:
Worse: if greeting is True: