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!
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:
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:
- _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()
from ThingsAndStuff import Thing t = Thing()
Import modules alphabetically in this order:
Python standard library modules
Modules from site-packages
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:
- 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.