Add note on line length to contributing guide
This commit is contained in:
+35
-14
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user