From 4df0075b4277e39f586a6a06d28ff2d3673b2c28 Mon Sep 17 00:00:00 2001 From: "Veronica K. B. Olsen" <1619840+vkbo@users.noreply.github.com> Date: Sat, 23 Jan 2021 11:10:59 +0100 Subject: [PATCH] Add note on line length to contributing guide --- CONTRIBUTING.md | 49 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 620fa7f1..fc03634e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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