mirror of
https://git.anonymousland.org/anonymousland/synapse.git
synced 2024-10-01 11:49:51 -04:00
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:
parent
356ed0438e
commit
b73ce4ba81
1
changelog.d/5719.misc
Normal file
1
changelog.d/5719.misc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Update the coding style document.
|
@ -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!
|
||||||
|
Loading…
Reference in New Issue
Block a user