Update the coding style doc (#5719)

A few fixes and removal of duplicated stuff, but mostly a bunch of the words on the config file.
This commit is contained in:
Richard van der Hoff 2019-07-19 11:55:14 +01:00 committed by GitHub
parent 356ed0438e
commit b73ce4ba81
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 100 additions and 35 deletions

1
changelog.d/5719.misc Normal file
View File

@ -0,0 +1 @@
Update the coding style document.

View File

@ -1,4 +1,8 @@
# Code Style Code Style
==========
Formatting tools
----------------
The Synapse codebase uses a number of code formatting tools in order to The Synapse codebase uses a number of code formatting tools in order to
quickly and automatically check for formatting (and sometimes logical) errors quickly and automatically check for formatting (and sometimes logical) errors
@ -6,18 +10,18 @@ in code.
The necessary tools are detailed below. The necessary tools are detailed below.
## Formatting tools - **black**
The Synapse codebase uses [black](https://pypi.org/project/black/) as an The Synapse codebase uses `black <https://pypi.org/project/black/>`_ as an
opinionated code formatter, ensuring all comitted code is properly opinionated code formatter, ensuring all comitted code is properly
formatted. formatted.
First install ``black`` with:: First install ``black`` with::
pip install --upgrade black pip install --upgrade black
Have ``black`` auto-format your code (it shouldn't change any Have ``black`` auto-format your code (it shouldn't change any functionality)
functionality) with:: with::
black . --exclude="\.tox|build|env" black . --exclude="\.tox|build|env"
@ -54,17 +58,16 @@ functionality is supported in your editor for a more convenient development
workflow. It is not, however, recommended to run ``flake8`` on save as it workflow. It is not, however, recommended to run ``flake8`` on save as it
takes a while and is very resource intensive. takes a while and is very resource intensive.
## General rules General rules
-------------
- **Naming**: - **Naming**:
- Use camel case for class and type names - Use camel case for class and type names
- Use underscores for functions and variables. - Use underscores for functions and variables.
- Use double quotes ``"foo"`` rather than single quotes ``'foo'``. - **Docstrings**: should follow the `google code style
<https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_.
- **Comments**: should follow the `google code style
<http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments>`_.
This is so that we can generate documentation with `sphinx This is so that we can generate documentation with `sphinx
<http://sphinxcontrib-napoleon.readthedocs.org/en/latest/>`_. See the <http://sphinxcontrib-napoleon.readthedocs.org/en/latest/>`_. See the
`examples `examples
@ -73,6 +76,8 @@ takes a while and is very resource intensive.
- **Imports**: - **Imports**:
- Imports should be sorted by ``isort`` as described above.
- Prefer to import classes and functions rather than packages or modules. - Prefer to import classes and functions rather than packages or modules.
Example:: Example::
@ -92,25 +97,84 @@ takes a while and is very resource intensive.
This goes against the advice in the Google style guide, but it means that This goes against the advice in the Google style guide, but it means that
errors in the name are caught early (at import time). errors in the name are caught early (at import time).
- Multiple imports from the same package can be combined onto one line::
from synapse.types import GroupID, RoomID, UserID
An effort should be made to keep the individual imports in alphabetical
order.
If the list becomes long, wrap it with parentheses and split it over
multiple lines.
- As per `PEP-8 <https://www.python.org/dev/peps/pep-0008/#imports>`_,
imports should be grouped in the following order, with a blank line between
each group:
1. standard library imports
2. related third party imports
3. local application/library specific imports
- Imports within each group should be sorted alphabetically by module name.
- Avoid wildcard imports (``from synapse.types import *``) and relative - Avoid wildcard imports (``from synapse.types import *``) and relative
imports (``from .types import UserID``). imports (``from .types import UserID``).
Configuration file format
-------------------------
The `sample configuration file <./sample_config.yaml>`_ acts as a reference to
Synapse's configuration options for server administrators. Remember that many
readers will be unfamiliar with YAML and server administration in general, so
that it is important that the file be as easy to understand as possible, which
includes following a consistent format.
Some guidelines follow:
* Sections should be separated with a heading consisting of a single line
prefixed and suffixed with ``##``. There should be **two** blank lines
before the section header, and **one** after.
* Each option should be listed in the file with the following format:
* A comment describing the setting. Each line of this comment should be
prefixed with a hash (``#``) and a space.
The comment should describe the default behaviour (ie, what happens if
the setting is omitted), as well as what the effect will be if the
setting is changed.
Often, the comment end with something like "uncomment the
following to \<do action>".
* A line consisting of only ``#``.
* A commented-out example setting, prefixed with only ``#``.
For boolean (on/off) options, convention is that this example should be
the *opposite* to the default (so the comment will end with "Uncomment
the following to enable [or disable] \<feature\>." For other options,
the example should give some non-default value which is likely to be
useful to the reader.
* There should be a blank line between each option.
* Where several settings are grouped into a single dict, *avoid* the
convention where the whole block is commented out, resulting in comment
lines starting ``# #``, as this is hard to read and confusing to
edit. Instead, leave the top-level config option uncommented, and follow
the conventions above for sub-options. Ensure that your code correctly
handles the top-level option being set to ``None`` (as it will be if no
sub-options are enabled).
* Lines should be wrapped at 80 characters.
Example::
## Frobnication ##
# The frobnicator will ensure that all requests are fully frobnicated.
# To enable it, uncomment the following.
#
#frobnicator_enabled: true
# By default, the frobnicator will frobnicate with the default frobber.
# The following will make it use an alternative frobber.
#
#frobincator_frobber: special_frobber
# Settings for the frobber
#
frobber:
# frobbing speed. Defaults to 1.
#
#speed: 10
# frobbing distance. Defaults to 1000.
#
#distance: 100
Note that the sample configuration is generated from the synapse code and is
maintained by a script, ``scripts-dev/generate_sample_config``. Making sure
that the output from this script matches the desired format is left as an
exercise for the reader!