Coding style, etc

[sbellem]

From @sbellem on August 24, 2017 21:9

The goal of this issue is to first list the various coding style elements for which there are multiple alternatives but yet for which some convention is sought in order to ease contributions, to make the code base uniform in style (to increase its readability) and to reduce potential unforeseen sources of disagreements regarding what could very often be considered unimportant trivial details.

Once a coding style element is identified, a convention can be agreed on.

PEP 8 -- Style Guide for Python Code

Since this is a Python project, PEP 8 -- Style Guide for Python Code is perhaps the first thing that should be considered. Automatic checkers such as flake8 (as mentioned in #33) can help in identifying coding style "errors". Yet, certain things need to be configured: We'll try to highlight some of the most common elements.

Maximum Line Length

It's best to read the section in PEP 8 on this matter. But here's the essence more or less, (quoting):

Limit all lines to a maximum of 79 characters.

For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters.
[...]
Some teams strongly prefer a longer line length. For code maintained exclusively or primarily by a team that can reach agreement on this issue, it is okay to increase the nominal line length from 80 to 100 characters (effectively increasing the maximum length to 99 characters), provided that comments and docstrings are still wrapped at 72 characters.

The Python standard library is conservative and requires limiting lines to 79 characters (and docstrings/comments to 72).

Imports

ref: https://www.python.org/dev/peps/pep-0008/#imports

The entire section should more or less be observed.

TODO: List important elements

Relative or absolute imports

TODO This needs to be decided

Imports in tests

This is not mentioned in PEP 8 and there can be a different style of using imports specifically for tests. One that is worth considering is: https://pylonsproject.org/community-unit-testing-guidelines.html

TODO: explain a bit https://pylonsproject.org/community-unit-testing-guidelines.html

String Quotes

ref: https://www.python.org/dev/peps/pep-0008/#string-quotes

In Python, single-quoted strings and double-quoted strings are the same. This PEP does not make a recommendation for this. Pick a rule and stick to it. When a string contains single or double quote characters, however, use the other one to avoid backslashes in the string. It improves readability.

For triple-quoted strings, always use double quote characters to be consistent with the docstring convention in PEP 257.

tool: https://github.com/zheller/flake8-quotes

PEP 257 -- Docstring Conventions

ref: https://www.python.org/dev/peps/pep-0257/

Testing Framework

This can perhaps be moved to its own issue for will put here for now.

Different test frameworks have their own set of features and plugins such that they are likely to be incompatible.

TODO list some examples (e.g.: nose2 vs pytest)
TODO pros and cons of different frameworks

reddit thread: Nose alternatives - nose2, pytest or something else?

Copied from original issue: amiller/HoneyBadgerBFT#34

[sbellem]

Additional useful references

• https://github.com/google/styleguide/blob/gh-pages/pyguide.md
• https://docs.python-guide.org/writing/style/
• http://flask.pocoo.org/docs/1.0/styleguide/
• https://docs.plone.org/develop/styleguide/python.html
• http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
• https://www.cs.bu.edu/courses/cs108/guides/style.html
• http://courses.cms.caltech.edu/cs11/material/python/misc/python_style_guide.html
• https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/

flake8 import order

• https://github.com/PyCQA/flake8-import-order
• https://github.com/PyCQA/flake8-import-order#styles

docs: https://github.com/openstack/doc8

cryptography project guidelines: https://cryptography.io/en/latest/development/submitting-patches/