Coding Conventions¶
The code must be compatible with the oldest supported version of python as given on the Installation page.
Importing modules¶
In code, like the implementation of ASE, we must not use the
import * syntax. Import everything explicitly from exactly the
place where it’s defined:
from ase.io import read, write
Python Coding Conventions¶
Please run pep8 and pyflakes on your code before committing.
The rules for the Python part are almost identical to those used by the Docutils project: project shall follow the generic coding conventions as specified in the Style Guide for Python Code and Docstring Conventions PEPs, summarized, clarified, and extended as follows:
- 4 spaces per indentation level. No hard tabs.
- Very important: Read the Whitespace in Expressions and Statements section of PEP8.
- Avoid introducing trailing whitespaces.
- Try to use only 7-bit ASCII, no 8-bit strings.
- No one-liner compound statements (i.e., no
if x: return: use two lines & indentation), except for degenerate class or method definitions (i.e.,
class X: passis OK.).
- Lines should be no more than 78 characters long.
- Use “StudlyCaps” for class names.
- Use “lowercase” or “lowercase_with_underscores” for function, method, and variable names. For short names, maximum two words, joined lowercase may be used (e.g. “tagname”). For long names with three or more words, or where it’s hard to parse the split between two words, use lowercase_with_underscores (e.g., “note_explicit_target”, “explicit_target”). If in doubt, use underscores.
- Avoid lambda expressions, which are inherently difficult to understand. Named functions are preferable and superior: they’re faster (no run-time compilation), and well-chosen names serve to document and aid understanding.
- Avoid functional constructs (filter, map, etc.). Use list comprehensions instead.
- Use ‘single quotes’ for string literals, and “”“triple double quotes”“” for docstrings. Double quotes are OK for something like
"don't".
- Parentheses, ] and } must never be left alone, sad and lonesome on their own line.
Attention.
Georg Brandl
Writing documentation in the code¶
Here is an example of how to write good docstrings:
Run pep8 and pyflakes on your code¶
It’s a good ide to run both the pep8 and pyflakes tools on your code (or use a text editor that does it automatically):
$ pep8 --ignore W293,E129 filename.py $ pyflakes filename.py
or equivalently:
$ alias check="python -m ase.utils.stylecheck" $ check filename.py
Install
pep8 and
pyflakes like this:
pip install pep8 pyflakes.
Using pylint to check your code¶
A pylintrc trying to follow ASE Coding Conventions can be found here:
pylintrc.