Add note on line length to contributing guide

This commit is contained in:
Veronica K. B. Olsen
2021-01-23 11:10:59 +01:00
parent af38fd3ba3
commit 4df0075b42
+35 -14
View File
@@ -8,8 +8,8 @@ There is a code of conduct. Please follow it in all your interactions with the p
## Pull Request Process
1. Make sure your code passes all tests and conforms to the style guide. You can check that the code
conforms by running `flake8` from the root of the project folder.
1. Make sure your code passes all tests and conforms to the style guide. You can check that the
code conforms by running `flake8` from the root of the project folder.
2. Please provide a complete description of the changes in the pull request, and a summary that can
be copied into the [CHANGELOG](CHANGELOG.md). Remember to reference any issue related by
providing the issue number.
@@ -22,20 +22,35 @@ There is a code of conduct. Please follow it in all your interactions with the p
In the interest of fostering an open and welcoming environment, we as contributors and maintainers
pledge to making participation in our project and our community a harassment-free experience for
everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level
of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
everyone, regardless of age, body size, disability, ethnicity, gender identity and expression,
level of experience, nationality, personal appearance, race, religion, or sexual identity and
orientation.
Please see the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file for the full text.
## Code Style Guide
The source code of novelWriter broadly follows the [PEP8](https://www.python.org/dev/peps/pep-0008/)
The source code of novelWriter broadly follows the [PEP8](https://www.python.org/dev/peps/pep-0008)
style guide , but with a few modifications and exceptions.
### Line Length
For this project, source lines should stay within the 79 and 99 character limits described by PEP8.
79 characters is often too restrictive, so 99 character lines are acceptable when that is more
practical. Readability has priority. Generally, if a code statement requires multiple lines, the
lines should wrap at 79 characters, not 99. If wrapping can be avoided by going to 99, then that is
preferrable.
For text files, the text should also be wrapped at 99 character. The exception is markdown image
tags and urls.
Please do not submit PRs that re-wrap existing source or text unless this has been discussed
beforehand.
### Linting with flake8
An excellent tool for checking Python code for errors and coding style is `flake8`.
The documentation is available [here](https://flake8.pycqa.org/en/latest/).
An excellent tool for checking Python code for errors and coding style is `flake8`. The
documentation is available [here](https://flake8.pycqa.org/en/latest/).
The `setup.cfg` file in the root of this project has the following settings:
```conf
@@ -57,20 +72,26 @@ not conform to the standard.
## Ignored Errors
Some errors are ignored in novelWriter, for various reasons. In addition, novelWriter uses camelCase
function and variable names due to this being the standard for the Qt libraries, and also because of
the author's personal preferences.
Some errors are ignored in novelWriter, for various reasons. In addition, novelWriter uses
camelCase function and variable names due to this being the standard for the Qt libraries, and also
because of the author's personal preferences.
The reason behind the other ignored error codes are listed below. Many of them are due to PEP8 not
permitting column alignment as opposed to many other coding styles. I find them useful in regions of
bulk value assignments. There's a reason why tables are more readable than lists. They should be
permitting column alignment as opposed to many other coding styles. I find them useful in regions
of bulk value assignments. There's a reason why tables are more readable than lists. They should be
used sparingly though.
The ignored errors are all `pycodestyle` errors, and they are documented
[here](https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes).
My main objection to PEP8 is the universal rejection of column alignment of blocks of code. In
particular when assigning variables and populating dictionaries. The PEP8 rule stands in contrast
to conventions from other code styles, like for Go. I have always used column alignment to a
certain degree in all programming languages I use, and I firmly believe it improves readability,
but should not be overused.
**E203:** whitespace before :
**Reason:** Column alignment. It is natural to align dictionary columns along the `:` character.
**Reason:** Column alignment.
**E221:** multiple spaces before operator
**Reason:** Column alignment.
@@ -78,7 +99,7 @@ The ignored errors are all `pycodestyle` errors, and they are documented
**E226:** missing whitespace around arithmetic operator
**Reason:** This doesn't actually follow the PEP8 recommendation of grouping longer equations by
operator precedence like `2*a + 3*b` instead of `a * a + 3 * b`. Generally, don't use spaces around
`*`, `/` and `**`, but do use spaces around `+` and `-`. For appending strings, the spaces can be
`*`, `/` and `**`, but _do_ use spaces around `+` and `-`. For appending strings, the spaces can be
dropped. Don't use the `+` operator for appending multiple strings. Use formatting instead.
**E228** missing whitespace around modulo operator