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 ## Pull Request Process
1. Make sure your code passes all tests and conforms to the style guide. You can check that the code 1. Make sure your code passes all tests and conforms to the style guide. You can check that the
conforms by running `flake8` from the root of the project folder. 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 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 be copied into the [CHANGELOG](CHANGELOG.md). Remember to reference any issue related by
providing the issue number. 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 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 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 everyone, regardless of age, body size, disability, ethnicity, gender identity and expression,
of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 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. Please see the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file for the full text.
## Code Style Guide ## 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. 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 ### Linting with flake8
An excellent tool for checking Python code for errors and coding style is `flake8`. An excellent tool for checking Python code for errors and coding style is `flake8`. The
The documentation is available [here](https://flake8.pycqa.org/en/latest/). documentation is available [here](https://flake8.pycqa.org/en/latest/).
The `setup.cfg` file in the root of this project has the following settings: The `setup.cfg` file in the root of this project has the following settings:
```conf ```conf
@@ -57,20 +72,26 @@ not conform to the standard.
## Ignored Errors ## Ignored Errors
Some errors are ignored in novelWriter, for various reasons. In addition, novelWriter uses camelCase Some errors are ignored in novelWriter, for various reasons. In addition, novelWriter uses
function and variable names due to this being the standard for the Qt libraries, and also because of camelCase function and variable names due to this being the standard for the Qt libraries, and also
the author's personal preferences. 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 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 permitting column alignment as opposed to many other coding styles. I find them useful in regions
bulk value assignments. There's a reason why tables are more readable than lists. They should be of bulk value assignments. There's a reason why tables are more readable than lists. They should be
used sparingly though. used sparingly though.
The ignored errors are all `pycodestyle` errors, and they are documented The ignored errors are all `pycodestyle` errors, and they are documented
[here](https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes). [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 : **E203:** whitespace before :
**Reason:** Column alignment. It is natural to align dictionary columns along the `:` character. **Reason:** Column alignment.
**E221:** multiple spaces before operator **E221:** multiple spaces before operator
**Reason:** Column alignment. **Reason:** Column alignment.
@@ -78,7 +99,7 @@ The ignored errors are all `pycodestyle` errors, and they are documented
**E226:** missing whitespace around arithmetic operator **E226:** missing whitespace around arithmetic operator
**Reason:** This doesn't actually follow the PEP8 recommendation of grouping longer equations by **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 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. dropped. Don't use the `+` operator for appending multiple strings. Use formatting instead.
**E228** missing whitespace around modulo operator **E228** missing whitespace around modulo operator