Nengo Bones attempts to enforce as much of this style guide as possible. However, since not everything can be automatically enforced, all Nengo developers should be familiar with this style guide and follow it when working on Nengo projects.
black for automated formatting.
We recommend that you set up your editor to run
when you save a Python file;
see Black editor integration
for details on how to do that.
Whether you set up
black with your editor or not,
you should run
black through a pre-commit hook.
To do this, first install pre-commit.
black and any other pre-commit hooks
that a project is using.
pylint for automated checks.
The exact options may vary from project to project,
so the easiest way to run these checks is to
.ci/static.sh script locally.
bones-generate --output-dir .ci ci-scripts && .ci/static.sh script
If you are missing any required packages,
.ci/static.sh install should install all requirements.
Class member order¶
In general, we stick to the following order for members of Python classes.
Class-level member variables (e.g.,
Parameters (i.e., instances of
nengo.params.Parameter) with the parameters in
__init__going first in that order, then parameters that don’t appear in
__init__in alphabetical order. All these parameters should appear in the Parameters section of the docstring in the same order.
Other special (
__x__) methods in alphabetical order, except when a grouping is more natural (e.g.,
@propertyproperties in alphabetical order.
@staticmethodmethods in alphabetical order.
@classmethodmethods in alphabetical order.
Methods in alphabetical order.
“Hidden” versions of the above (i.e., anything starting with an underscore) should either be placed right after they’re first used, or at the end of the class.
These are guidelines that should be used in general, not strict rules. If there is a good reason to group differently, then feel free to do so, but please explain your reasoning in a code comment or commit message.
NumPy’s guidelines for docstrings,
as they are readable in plain text and when rendered with Sphinx.
We use the default role of
obj in documentation,
so any strings placed in backticks in docstrings
will be cross-referenced properly if they
unambiguously refer to something in the Nengo documentation.
See Cross-referencing syntax
and the Python domain
for more information.
We use several advanced
git features that
rely on well-formed commit messages.
Commit messages should fit the following template.
Capitalized, short (50 chars or less) summary More detailed body text, if necessary. Wrap it to around 72 characters. The blank line separating the summary from the body is critical. Paragraphs must be separated by a blank line. - Bullet points are okay, too. - Typically a hyphen or asterisk is used for the bullet, followed by single space, with blank lines before and after the list. - Use a hanging indent if the bullet point is longer than a single line (like in this point).
JS, TS, CSS, HTML, etc