Code style¶
This section contains some code style guidelines for the different programming languages used in the project.
Python¶
Follow PEP 8, the linting tools below can find PEP 8 problems for you automatically.
Docstrings¶
All public modules, functions, classes, and methods should normally have docstrings. See PEP 257 for general advice on how to write docstrings (although we don’t write module docstrings that describe every object exported by the module).
The pep257
tool (which is run by prospector
, see below) can point out
PEP 257 violations for you.
It’s good to use Sphinx references in docstrings because they can be syntax highlighted and hyperlinked when the docstrings are extracted by Sphinx into HTML documentation, and because Sphinx can print warnings for references that are no longer correct:
- Use Sphinx Python cross-references to reference other Python modules, functions etc. from docstrings (there are also Sphinx domains for referencing objects from other programming languages, such as JavaScript).
- Use Sphinx info field lists to document parameters, return values and exceptions that might be raised.
- You can also use reStructuredText to add markup (bold, code samples, lists, etc) to docstrings.
Linting¶
We recommend running Flake8 and Prospector over your code to find bugs and style problems, using the configurations provided in this git repo. With our configurations Flake8 is faster and less noisy so is nicer to run more frequently, Prospector is more thorough so it can be run less frequently and may find some problems that Flake8 missed.
Automated code formatting¶
You can use YAPF (along with the YAPF configuration in this git repo) to automatically reformat Python code. We don’t strictly adhere to YAPF-generated formatting but it can be a useful convenience.
Additional reading¶
- Although we don’t strictly follow all of it, the Google Python Style Guide contains a lot of good advice.
Front-end Development¶
See the Hypothesis Front-end Toolkit repository for documentation on code style and tooling for JavaScript, CSS and HTML.