-
Notifications
You must be signed in to change notification settings - Fork 13
Style Guide
Conform to PEP8 as much as possible/sensible.
As far as possible, keep to the 72, 79 character PEP8 guideline for docstrings and code respectively.
Breaking docstrings/code across lines where it hurts readability is not advised, although a hard limit of 100 characters is expected.
For example if stdout print(f"The minimum and maximum are: {minimum} and {maximum})"
could be a compliant one-liner by reducing variable names to mini
and maxi
(to avoid the clearer shortening of min
and max
that would overwrite Python's built-in functions), then leave the line the way it is.
Inline comments on their own line should respect the limit, but comments inline following code may extend out to 120 characters, if necessary. Consideration should be given whether clarity would be retained by placing the comment on it's own line.
Clear, well documented code is the goal.
Broadly speaking, docstrings should follow ReStructuredText (reST) format:
def func(arg1: int, arg2: str):
"""
Summary line.
Extended description of function.
:param arg1: int, description of arg1. # eg :param param-name: param-type, description
:param arg2: str, description of arg2.
:raises ValueError if arg1 is equal to arg2
:return: None, description of return value
"""
Groups of parameters/raised errors/return can be separated by a blank line for clarity. The PEP8 72 character limit for docstrings should be respected.
Use type hints. This can be invaluable for avoiding/finding bugs!
Generally, follow PEP8. Group import x
and from x import y
styles together, generally adding newlines for visual clarity, and brackets where multiple imports from one module exceed allowed line length.
This project follows the following style:
import stdlib module
from stdlib_module import function
from subsequent_stdlib_module import another_function
import third_party_module
from third_party_module import function
import local_application_module
from local_application_module import function
from long_local_application_module import (function_1
function_2,
function_3,
function_4,
function_5,
)