Neopythonic. Patterns in Python. Python Coding Guidelines. Written by Rob Knight for the Cogent project Table of Contents Why have coding guidelines? As project size increases, consistency increases in importance. This project will start with isolated tasks, but we will integrate the pieces into shared libraries as they mature. Good code is useful to have around. What should I call my variables? Choose the name that people will most likely guess. Good names are hard to find. Use singular names for individual things, plural names for collections. Don't make the type part of the name. Make the name as precise as possible. Use result to store the value that will be returned from a method or function. One-letter variable names should only occur in math functions or as loop iterators with limited scope. Limit your use of abbreviations. Acceptable abbreviations. Full abbreviated alignment aln archaeal arch auxillary aux bacterial bact citation cite current curr database db dictionary dict directory dir end of file eof eukaryotic euk frequency freq expected exp index idx input in max mt.
PEP 257 -- Docstring Conventions. What is a Docstring? A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object. All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings.
A package may be documented in the module docstring of the __init__.py file in the package directory. String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to __doc__), but two types of extra docstrings may be extracted by software tools: Please see PEP 258, "Docutils Design Specification" , for a detailed description of attribute and additional docstrings. XXX Mention docstrings of 2.2 properties. Multi-line Docstrings. PEP 8 -- Style Guide for Python Code. Code should be written in a way that does not disadvantage other implementations of Python (PyPy, Jython, IronPython, Cython, Psyco, and such).For example, do not rely on CPython's efficient implementation of in-place string concatenation for statements in the form a += b or a = a + b.
This optimization is fragile even in CPython (it only works for some types) and isn't present at all in implementations that don't use refcounting. In performance sensitive parts of the library, the ''.join() form should be used instead. This will ensure that concatenation occurs in linear time across various implementations.Comparisons to singletons like None should always be done with is or is not, never the equality operators.Also, beware of writing if x when you really mean if x is not None -- e.g. when testing whether a variable or argument that defaults to None was set to some other value. The other value might have a type (such as a container) that could be false in a boolean context!