|
Size: 2866
Comment:
|
Size: 4923
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 24: | Line 24: |
| __email__ = "rob@spot.colorado.edu" | __email__ = "rob@example.com" |
| Line 108: | Line 108: |
| }}} |
|
| Line 147: | Line 144: |
| Line 156: | Line 151: |
== Function/class documentation == pydoc has no standard (it just prints docstrings as-is). [[https://www.python.org/dev/peps/pep-0257/|PEP257: Docstring Conventions]] specifies some stuff, but it is not very structured. [[https://www.python.org/dev/peps/pep-0287/|PEP287: reStructuredText Docstring Format]] also has some info. [[http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html?highlight=domains#id3|Sphinx has some standards]]. [[https://sphinxcontrib-napoleon.readthedocs.io/en/latest/|Napoleon format]], specified in Google's Python Style Guide, is very readable and has a module for Sphinx. [[https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard|numpy has it's own docstring style guide]]. == Other resources == * [[http://code.google.com/p/soc/wiki/PythonStyleGuide|PythonStyleGuide - soc - Style guide for Python code contributed to Melange - SoC (Spice of Creation) - Google Project Hosting]] * [[https://google.github.io/styleguide/pyguide.html|Google Python Style Guide]] * [[https://github.com/google/yapf|google/yapf: A formatter for Python files]]. clang-format-like, similar to gofmt == Parsing JSON == Rather than doing {{{#!highlight python numbers=off blah['one']['two'] }}} Python 3.3+ has the !SimpleNamespace module: {{{#!highlight python numbers=off import types my_dict = { 'one': {'two': 2} } blah = SimpleNamespace(**my_dict) print(blah.one.two) }}} There are also 3rd-party libraries like [[https://pypi.org/project/python-box/|python-box]] == Lectures == === PyCon 2015: Beyond PEP8: Best practices for beautiful intelligible code === [[https://www.youtube.com/watch?v=wf-BqAjZb8M|Raymond Hettinger - Beyond PEP 8 -- Best practices for beautiful intelligible code - PyCon 2015 - YouTube]] * 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! |
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 citation cite current curr database db dictionary dict directory dir end of file eof eukaryotic euk frequency freq expected exp index idx input in 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 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). 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.
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
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!
