mirror of
https://github.com/codex-storage/deluge.git
synced 2025-01-22 17:29:19 +00:00
89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# Coding Styles
|
|
|
|
## Common
|
|
* Line length: Maximum of `119` rather than usual `79`. That said, where possible keep it between `79-99` to keep it readable.
|
|
* Indent: `4 spaces`, no tabs.
|
|
* All code should use `'single quotes'`.
|
|
|
|
## Python
|
|
Deluge follows [PEP8](http://www.python.org/dev/peps/pep-0008/) and [Python Code Style](http://docs.python-guide.org/en/latest/writing/style/) with line length the only exception.
|
|
|
|
* Code **must** pass [flake8](https://pypi.python.org/pypi/flake8) (w/[flake8-quotes](https://pypi.python.org/pypi/flake8-quotes)), [isort](https://pypi.python.org/pypi/isort) and [Pylint](http://www.pylint.org/) source code checkers.
|
|
|
|
```
|
|
flake8 deluge
|
|
isort -rc -df deluge
|
|
pylint deluge
|
|
pylint deluge/plugins/*/deluge/
|
|
```
|
|
|
|
* Using the [pre-commit](http://pre-commit.com/) app can aid in picking up issues before creating git commits.
|
|
|
|
* All byte strings (`str`) should be decoded to strings (unicode strings, `unicode`) on input and encoded back to byte strings on output. [From Stackoverflow:](http://stackoverflow.com/a/606199/175584)
|
|
|
|
```
|
|
>>> b"abcde"
|
|
b'abcde'
|
|
>>> b"abcde".decode("utf-8")
|
|
'abcde'
|
|
```
|
|
*Notes:*
|
|
* *PyGTK/GTK+ will accept `str` (utf8 encoded) or `unicode` but will only return `str`. See [GTK+ Unicode](http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html) docs. *
|
|
|
|
* *There is also a `bytearray` type which enables in-place modification of a string. See [Python Bytearrays](http://stackoverflow.com/a/9099337/175584) *
|
|
|
|
* *For reference Python 3 renames `unicode` to `str` type and byte strings become `bytes` type. *
|
|
|
|
|
|
* All relative path separators used within code should be converted to posix format `/`, so should not contain `\` or `\\`. This is to prevent confusion when dealing with cross-platform clients and servers.
|
|
|
|
### Docstrings
|
|
|
|
You will find a mix of the older [reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html) and newer, easier to read, [Sphinx Napoleon](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/) format.
|
|
|
|
Going forward the Napoleon [Google Style](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html) will be used for all new doctrings and eventually convert over the rest.
|
|
|
|
Google Style short example:
|
|
|
|
```
|
|
def func(arg):
|
|
"""Function purpose.
|
|
|
|
Args:
|
|
arg (type): Description.
|
|
|
|
Returns:
|
|
type: Description. If the line is too, long indent next
|
|
line with three spaces.
|
|
|
|
"""
|
|
```
|
|
|
|
Most common sections are `Args` and `Returns`. See complete list of [supported headers](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#docstring-sections).
|
|
|
|
Verify that the documentation parses correctly with:
|
|
|
|
```
|
|
python setup.py build_docs
|
|
```
|
|
|
|
### Python References
|
|
|
|
Useful links to style guides from other projects:
|
|
|
|
* [CKAN Python coding standards](http://docs.ckan.org/en/latest/contributing/python.html)
|
|
* [Google Python Style Guide](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html)
|
|
* [Best of the Best Practices Guide for Python](https://gist.github.com/sloria/7001839)
|
|
|
|
## Javascript
|
|
|
|
Using [codepainter](https://github.com/jedmao/codepainter) with `hautelook` style will ensure a consistent coding style.
|
|
|
|
```
|
|
codepaint xform -p hautelook "file.js"
|
|
```
|
|
|
|
* Classes should follow the Ext coding style.
|
|
* Class names should be in CamelCase
|
|
* Instances of classes should use camelCase.
|