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
|
||||
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user