Python

Should follow PEP-8

Quick overview

• 4 spaces as tabs

• snake_case for variables, functions and modules

• PascalCase for classes

• Global variables should not be used.

• Global constants should be in SCREAMING_CASE when used.

• Lines should not be longer than 80 characters

• Use trailing commas when the closing bracket is on a new line

• Space after comments e.g. # something

• Protected methods and attributes to start with _, private to start with __

• When a variable is not used, give it the name _ e.g.

  for _ in range(10):
      print("Hi")
  
  (important_var, _) = some_func()

Non-biased opinions

• Try to prioritise readability of code

• Order imports alphabetically but split internal imports

• Comments should only be written when necessary, mainly to describe why something is done the way it is or to example a really unreadable bit of code (however this normally means you should change the code).

• Methods should be ordered alphabetically (with private methods ordered separately and at the bottom of the file) e.g.

  def a_func():
      ...
  
  def b_func():
      ...
  
  def z_func():
      ...
  
  def _a_private_func():
    ...
  
  def _b_private_func():
    ...

• Please use statically-typed code when possible: always for functions and parameters and then only for variables when its hard to tell e.g.

  MY_CONST: dict[str, set[list[(str|int)]]] = {
      "something": set(["hi"], [2], [3]),
  }
  
  def my_func(param1: int, param2: list[str]) -> (dict[str, int]|None):
      my_variable = "hi"
      ...
  
  def void_func():
      ...

  However note that we should try to avoid using the str|int type and keep to one type when possible.

• Generators are cool but don’t over use them and format them to be more readable with good naming schemes. e.g.

  cube = np.from_iter((
      (y + x for x in range(10))
      for y in range(10)
  ), ...)

Using Pylint

On most IDEs (including vscode) you should be able to get a pylint extension to point out mistakes and annoy you into writing okay code. Please use this as it should help you with the above styling requirements.

You can also use flake8 (however these are really strict and I don’t like some of them), so here is an example configuration (in the .flake8 file):

[flake8]
extend-ignore = E272,E221,E227,E201,E202
exclude = .git,__pycache__
max-complexity = 10

Documentation

There is annoyingly no exact style in python for these… Here is something I kinda like.

Documentation should be for all public modules, methods, classes and functions (however please also try to do them for private versions, but they don’t have to be as indepth).

The style of documentation is kinda whatever you want it to be, so here is a somewhat okay layout. (Any better styles are most welcome as long as we are consistent)

Example:

example_module.py

"""
Description
"""

def my_func(param1: int) -> str:
    """Description of return which fits in less than 80 chars"""
    ...

def my_complex_func(param1: list[str]):
    """
    Description

    Parameters
    ----------
    param1 (type): Description

    Return
    ------
    brief_name (type): Description
    """

class MyClass:
  """
  Description

  Attributes
  ----------
  ...
  """

  def my_method():
    """..."""
  ...