Coding and Related Guidelines

Coding Guidelines

These style guidelines are based on the Python PEP 8. To consult the Document go to:

Naming Conventions

  1. Module names

  2. Imported modules

    It is desirable to do this:
    import module_name as moduleName (lower camelCase)

  3. Class names

    MyClass() (CamelCase plus parenthesis)

  4. Method names

    myFunction() (lower camelCase plus parenthesis)

  5. Variable Names

    myVariable (lower camelCase)

Code lay-out

  1. Indentation

    Use 4 space-tabs per indentation level.

  2. Tabs or Spaces?

    We prefer tabs. In any case, never mix tabs and spaces.

  3. Maximum Line Length
    • Limit all lines to a maximum of 79 characters.
    • For flowing long blocks of text (docstrings or comments), limiting the length to 72 characters is recommended.
  4. Blank Lines
    • Separate top-level function and class definitions with three blank lines.
    • Method definitions inside a class are separated by two blank lines.
    • Extra blank lines may be used (sparingly) to separate groups of related functions.
    • Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).
    • Use blank lines in functions, sparingly, to indicate logical sections.


  1. Imports should usually be on separate lines, e.g.:

    import os
    import sys

    import os, sys

    it's okay to say this though:
    from subprocess import Popen, PIPE

  2. Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants.
  3. Imports should be grouped in the following order:
    1. standard library imports
    2. related third party imports
    3. local application/library specific imports

    You should put a blank line between each group of imports.

    Put any relevant __all__ specification after the imports.

  4. When importing a class from a class-containing module, it's usually okay to spell this:

    from myclass import MyClass

    from import YourClass

  5. If this spelling causes local name clashes, then spell them:

    <<<<<<< .mine

    import myclass


    and use myclass.MyClass and


    import myclass


    and use

    >>>>>>> .r381

Whitespace in Expressions and Statements

Avoid extraneous whitespace in the following situations:

  1. Immediately inside parentheses, brackets or braces:

    spam(ham[1], {eggs: 2})

    spam( ham[ 1 ], { eggs: 2 } )

  2. Immediately before a comma, semicolon, or colon:

    if x == 4: print x, y; x, y = y, x

    if x == 4 : print x , y ; x , y = y , x

  3. Immediately before the open parenthesis that starts the argument list of a function call:


    spam (1)

  4. Immediately before the open parenthesis that starts an indexing or slicing:

    dict['key'] = list[index]

    dict ['key'] = list [index]

  5. More than one space around an assignment (or other) operator to align it with another.

    x = 1
    y = 2
    long_variable = 3

    NO (the underscores represent whitespace):
    x_____________= 1
    y_____________= 2
    long_variable_= 3

Other Recommendations

  1. 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)
  2. 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)

  3. Don't use spaces around the '=' sign when used to indicate a keyword argument or a default parameter value.

    Yes (the underscores represent whitespace):
    def complex(real, imag=0.0):
    ____return magic(r=real, i=imag)

    NO (the underscores represent whitespace):
    def complex(real, imag = 0.0):
    ____return magic(r = real, i = imag)

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

    Yes (the underscores represent whitespace):
    if foo == 'blah':

    Rather not:
    if foo == 'blah': do_blah_thing()
    do_one(); do_two(); do_three()

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


  1. 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!
  2. 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!).
  3. If a comment is short, the period at the end can be omitted.
  4. Block comments generally consist of one or more paragraphs built out of complete sentences, and each sentence should end in a period.
  5. When writing English, Strunk and White apply.
  6. Python coders from non-English speaking countries: please write your comments in English, unless you are 120% sure that the code will never be read by people who don't speak your language.

Block Comments

  1. 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).
  2. Paragraphs inside a block comment are separated by a line containing a single #.

Inline Comments

  1. Use inline comments sparingly.
  2. 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.
  3. 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

  1. 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.
  2. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.:

    """ This is an example docstring. The closing quotations are on an independent line.

  3. After the docstring comment, indicate the input and output of the function. Input and output names shoulod be in an ordered list, followed by "--->" (inputs) or -->> (outputs), and a small comment explaining what the input/ouput is, e.g.(the underscores represent whitespace):

    def myFunction(word, dictionary):
    """ This unnecesary function looks for a word in a dictionary.
    word__________---> a string to be looked-up in a dictionary
    dictionary____---> a python dictionary
    return________-->> the word's entry

Version Numbering