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).
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.
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):
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
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