File organization
- The Encoding
- The Copyright
- The License
- The Documentation String
- The Imports
- Authorship information
- The Code
1 # -*- coding: UTF-8 -*-
2 # Copyright (C) YEARS AUTHOR-NAME <AUTHOR-EMAIL>
3
4
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__ = "rob@example.com"
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
Comments should be full sentences, end with a period.
Abbreviations
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
and
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.
over
over
The latter is acceptable if line 1 or any of the arguments are long. E.g.:
ElementTrees/XML parsing
Use elem for unknown elements.
Prefix 'x' onto elements/trees. E.g. for <body> use xbody, <table> use xtable, etc.
From: http://self.maluke.com/style
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.
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
google/yapf: A formatter for Python files. clang-format-like, similar to gofmt
Parsing JSON
Rather than doing
blah['one']['two']
Python 3.3+ has the SimpleNamespace module:
import types
my_dict = {
'one': {'two': 2}
}
blah = SimpleNamespace(**my_dict)
print(blah.one.two)
There are also 3rd-party libraries like python-box
Lectures & Videos
PyCon 2015: Beyond PEP8: Best practices for beautiful intelligible code
Adding an arbitrary line break to make a line <= 80 characters, shortening variable names, etc does NOT make code better.
- "Foolish consistency is the hobgoblin of little minds" — right at the top of PEP8, people read right through it!
PyCon 2016: Refactoring Python: Why and How to Restructure Your Code is also relevant (not technical enough to need notes).
