James Madison University , Spring 2013

James Madison University Python Coding Conventions
By Nathan Sprague

We will 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__":
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:

      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.
      Best practice: avoid tabs at all!

  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)


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

        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.


          x = 1
          y = 2
          long_variable = 3


          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:


          i = i + 1
          submitted += 1
          x = x * 2 - 1
          hypot2 = x * x + y * y
          c = (a + b) * (a - b)


          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.


          def complex(real, imag=0.0):
              return magic(r=real, i=imag)


          def complex(real, imag = 0.0):
              return magic(r = real, i = imag)

    - Compound statements (multiple statements on the same line) are
      generally discouraged.


          if foo == 'blah':

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


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

    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

Module headers should include a brief description of the module as well as author and version information. A separate block comment should include your honor code statement.

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
          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
      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
          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: