You should read this document if you intend to contribute code to ASE. It is a standard that we follow unless there is a good reason not to. But people who find a rule utterly disgusting may disregard it!

The style that we recommend is similar to what is recommended on the official python homepage (see PEP 8 and PEP 257).

There is an excelent tool called pylint that is quite fun and useful. Pylint is a python tool that checks if a module satisfy a coding standard - try it on your code like this:

[hugo@cpu1 hugo]$ pylint code.py

You should copy the ASE configuration file for pylint to your home directory:

[hugo@cpu1 hugo]$ cp ASE/pylintrc ~/.pylintrc

You can find examples of good coding style in:

Recommendations

Here is a list of recommendations. The first two are very important:

  • No line should exceed 79 characters.

  • Indentations should be four spaces.

    emacs: The Python mode does this automatically.

    vim: Put this in your .vimrc:

    set tabstop=4
    set shiftwidth=4
    set expandtab
    set autoindent
  • Functions, classes and methods should mostly have names like this:

    • FunctionName()
    • ClassName()
    • MethodName()
    • _PrivateMethodName() (for methods not to be used by a user)
  • Don't do from ThingsAndStuff import *. Do this instead:

    import ThingsAndStuff as ts
    t = ts.Thing()

    or:

    from ThingsAndStuff import Thing
    t = Thing()
  • Import modules alphabetically in this order:

    1. Python standard library modules

    2. Modules from site-packages

    3. Other modules

    If there is a good reason for delaying an import to a function or a method call, please place a comment right after the ordinary imports saying that module Stuff is imported in method Thing.DoStuff().

  • use import Numeric as num (Numeric will be replaced by scipy-core someday in the future).

  • When writing something quick and dirty or just questionable add a comment containing "?????". Then one can easily find those places by doing:

    grep '???' *.py
  • Code that is commented out has the '##' in column 1-2, so that it can be distinguished from real comments that have an indented '#' (emacs is confused by a single '#' in the first column).

  • Names of variables should typically be:

    • short
    • all lower case
    • with no leading or trailing underscores
    • a leading underscore is OK for global variables that should not be imported by a from module import *.
  • Try not to use \ for continuation (use parentheses).

  • Use space around '=', '+', '-', '==' and so on. Exception: No space around '=' in default arguments:

    def sum(x=7, y=117):
        s = x + y
        return s
  • Only one class in each file (unless those classes are small and related).

  • Avoid loops over atoms, if array operations will do. Remember, your module may be used for a 14-atoms dacapo calculation today, but in a 50 million atoms asap calculation tomorrow.

  • When fixing a bug: Write a test script to catch it and add it to the ASE/Tests directory. Click here for details.

ase2: Code_standard (last edited 2010-10-20 09:11:15 by localhost)