Coding style guide for the Ghostwriter code base
python
)
Isort
which is part of the Python extensions Python Refactor
toolkit (Python Refactor: Sort Imports
).
isort
by pressing SHIFT+CMD+P and selecting Python Refactor: Sort Imports
.
You probably noticed the peculiar default line length. Black defaults to 88 characters per line, which happens to be 10% over 80. This number was found to produce significantly shorter files than sticking with 80 (the most popular), or even 79 (used by the standard library). In general, 90-ish seems like the wise choice.The Ghostwriter project does not use 88 because it is registered as a numerical hate symbol by the Anti-Defamation League.
Isort
defaults to 79 to match PEP-8, so a line length must be configured to avoid style conflicts.
For these reasons, the Ghostwriter project requires maximum line length be between 90 and 119-characters to keep everything comfortable to read in code editors and on GitHub. Any lines shorter than 90 should not be split, and longer lines should not exceed 119-characters without reason.
"""
which deviates from standard practice (per PEP-8). Further, the use of grave accents, asterisks ( * ), and colons ( : ). are all purposeful and important. Django and docutils
convert these symbols into formatting for the auto-generated documentation in the admin panel.
The above example is rendered like this:
flake8
to lint Ghostwriter’s code. The VSCode Python extension natively supports linting and a variety of linters.
https://code.visualstudio.com/docs/python/lintingcode.visualstudio.com
The project recommends changing VSCode’s default PyLint
to flake8
because this linter is much faster and snappier – especially with some of Ghostwriter’s longer Python files (e.g., a views.py). The flake8
linter is logical and stylistic, like PyLint
. Black should handle most of the linting, but it won’t flag unused imports.
When the linter returns errors or warnings, VSCode changes the filename to yellow or red. The editor also displays squiggles under the affected lines.
Address all linting issues before committing any code. At a minimum, eliminate trailing whitespace and remove unused imports.
Git hook scripts are useful for identifying simple issues before submission to code review. We run our hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks.First, install the library by running
pip install pre-commit
for your local development environment.
Add a .pre-commit-config.yaml
file to the project’s root directory. Use the example below as a model for this file.
Once the file is in place, run pre-commit install
to hook future git commits.