diff options
| author | Bernát Gábor <bgabor8@bloomberg.net> | 2021-01-16 09:39:21 +0000 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-01-16 09:39:21 +0000 |
| commit | d9c5b9cc6c4aa6a4cd477b3dbb5b8e09efcb922a (patch) | |
| tree | c14cfbd35f9ebd911c5b4f8b19e00f8e471e0e13 | |
| parent | b4e860c1f72c2537fc332ff20581f15a25b801b9 (diff) | |
| download | tox-git-d9c5b9cc6c4aa6a4cd477b3dbb5b8e09efcb922a.tar.gz | |
Add code style guide (#1827)
Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
| -rw-r--r-- | docs/changelog/1734.doc.rst | 1 | ||||
| -rw-r--r-- | docs/development.rst | 20 |
2 files changed, 19 insertions, 2 deletions
diff --git a/docs/changelog/1734.doc.rst b/docs/changelog/1734.doc.rst new file mode 100644 index 00000000..e306261b --- /dev/null +++ b/docs/changelog/1734.doc.rst @@ -0,0 +1 @@ +Add code style guide for contributors - by :user:`gaborbernat`. diff --git a/docs/development.rst b/docs/development.rst index 6db89326..7eb9361c 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -83,12 +83,28 @@ run: .. code-block:: shell - tox -e fix_lint + tox -e fix .. note:: Avoid using ``# noqa`` comments to suppress linter warnings - wherever possible, warnings should be fixed instead. - ``# noqa`` comments are reserved for rare cases where the recommended style causes severe readability problems. + ``# noqa`` comments are reserved for rare cases where the recommended style causes severe readability problems or + sidestep bugs within the linters. + +Code style guide +~~~~~~~~~~~~~~~~ + +- First and foremost, the linters configured for the project must pass; this generally means following PEP-8 rules, + as codified by: ``flake8``, ``black``, ``isort``, ``pyupgrade``. +- Packaging options should be specified within ``setup.cfg``, ``setup.py`` is only kept for editable installs. +- All code (tests too) must be type annotated as much as required by ``mypy``. +- We use a ling length of 120. +- Exception messages should only be capitalized (and ended with a period/exclamation mark) if they are multi-sentenced, + which should be avoided. Otherwise, use statements that start with lowercase. +- All function (including test) names must follow PEP-8, so they must be fully snake cased. All classes are upper + camel-cased. +- Prefer f-strings instead of the ``str.format`` method. +- Tests should contain as little information as possible but do use descriptive variable names within it. Building documentation ~~~~~~~~~~~~~~~~~~~~~~ |