Code style

Read pep8 and use it as first place style guide

These rules may add, overwrite or emphasize pep8 ones:

Logic

• Don't put large code with multiple actions in one line. Split it into several lines in accordance with functional logic

• Don't place a code for debugging in PR. All variables and additional checks needed for DEBUG only should be done locally. Exception: if you need code that always saves debugging info during debug session, you can leave this code, but it will be executed only if program launched in debug session (check environment var)

Naming

• Give sensible names for functions, vars, and constants

• Don't use temp 1-letter vars such as "i". Every variable, even counter in a loop, should describe its purpose.

• Name of a function should be started with a verb and shortly describe what func do.

• Constants are usually defined on a module level and written in all capital letters with underscores separating words. Examples include MAX_OVERFLOW and TOTAL.

Typing

• Each function or class's field has to be annotated with type hints
• typing module is used for this
• PEP 483 is simplified introduction to type hints

Documentation

docstring guide describes how to make documentation for your code

Highlights:

• The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

• Docstring should be used ONLY for explaining function's interface, not for its internal variables. For the explanation of code use plain comment above (or on right) of a line, you want to clarify.

• The closing quotes are on the same line as the opening quotes. This looks better for one-liners.

• There's no blank line either before or after the docstring.

• The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

• The one-line docstring should NOT be a "signature" reiterating the function/method parameters (which can be obtained by introspection). Don't do:

def function(a, b): """function(a, b) -> list"""