File organization

   1 # -*- coding: UTF-8 -*-
   5 __author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
   6 __copyright__ = "Copyright 2007, The Cogent Project"
   7 __credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
   8                     "Matthew Wakefield"]
   9 __license__ = "GPL"
  10 __version__ = "1.0.1"
  11 __maintainer__ = "Rob Knight"
  12 __email__ = ""
  13 __status__ = "Production"

Status should typically be one of "Prototype", "Development", or "Production". maintainer should be the person who will fix bugs and make improvements if imported. credits differs from author in that credits includes people who reported bug fixes, made suggestions, etc. but did not actually write the code.


Comments should be full sentences, end with a period.

   1 def aLongFunction(x, y, z):
   2     # 2000 lines of code follow...
   3     return 1
   4 # end aLongFunction


alignment       aln
archaeal        arch
auxillary       aux
bacterial       bact
character  ch
citation        cite
current         curr
database        db
dictionary      dict
directory       dir
end of file     eof
eukaryotic      euk
frequency       freq
expected        exp
index   idx
input   in
length  ln
maximum         max
minimum         min
mitochondrial   mt
number  num
observed        obs
original        orig
output  out
phylogeny       phylo
previous        prev
protein         prot
record  rec
reference       ref
sequence        seq
standard deviation      stdev
statistics      stats
size  sz
string  str
structure       struct
temporary       temp
taxonomic       tax
variance        var


class cls
thread th
transaction txn
deferred dfd
format fmt
template tmpl
implementation impl
button btn_*
checkbox chk_*
middleware *_mw
callback cb
filename fn
file object f

re_ for regular expression strings.

rx_ for compiled regular expressions.

m for matches.

r for return values.

Function calls

Attempt to minimize vertical space, while not compromising readability.

   1 result = someFunction(one, two,
   2                       three)


   1 result = someFunction(
   2     one, two,
   3     three)


   1 result = someFunction(
   2     one, two,
   3     three
   4 )

The latter is acceptable if line 1 or any of the arguments are long. E.g.:

   1 result = someFunctionWithALongName(
   2     one, two,
   3     aLongThirdArgument
   4 )

ElementTrees/XML parsing

Use elem for unknown elements.

Prefix 'x' onto elements/trees. E.g. for <body> use xbody, <table> use xtable, etc.


Function/class documentation

pydoc has no standard (it just prints docstrings as-is), but the core Python documentation has some tone/etc guidelines. PEP257: Docstring Conventions specifies some stuff, but it is not very structured. PEP287: reStructuredText Docstring Format also has some info.

Sphinx has some standards.

Napoleon format, specified in Google's Python Style Guide, is very readable and has a module for Sphinx. Comprehensive example list.

numpy has it's own docstring style guide.

Other resources

Parsing JSON

Rather than doing


Python 3.3+ has the SimpleNamespace module:

import types

my_dict = {
    'one': {'two': 2}

blah = SimpleNamespace(**my_dict)

There are also 3rd-party libraries like python-box

Lectures & Videos

PyCon 2015: Beyond PEP8: Best practices for beautiful intelligible code

Raymond Hettinger - Beyond PEP 8 -- Best practices for beautiful intelligible code - PyCon 2015 - YouTube

PyCon 2016: Refactoring Python: Why and How to Restructure Your Code is also relevant (not technical enough to need notes).

SamatsWiki: CodingStyle/Python (last edited 2020-04-05 10:22:57 by SamatJain)