Coding style

Guidelines on how to write and style code

HTML

  • Use class to set the CSS style rather than using a style attribute.

Python

  • Avoid “magic” in how code works:
    • Keep input/output predictable and consistent
    • Avoid “side effects” (actions that are not part of the output)
  • Prefer using functional programming over object-oriented programming.
  • Write type hints for inputs and returns.
  • Most functions and methods should prefer to have a single, simple action. More complex actions (especially user-facing ones) done by a function should chain together the smaller functions to achieve the larger action.

docstrings

  • Write docstrings for every function, class, and method.
    • Use the """ triple quotes for docstrings.
    • Use sentence case for describing things and end with a full stop.
      So use path: The path to the file. rather than path: the path to the file.
    • Use a tab when creating a new line for the description.
  • Use the Google style for writing the docstrings. When adding docstrings in Seedcase projects this will automatically be added by the autoDocstring VS Code extension.
  • Write simple one-line docstrings for: very small functions (<5 lines), functions with <2 arguments, and functions with simple and clear input and output
  • Write longer and more detailed docstrings for: larger functions, functions with several arguments, user-facing functions, and those with more complex or non-standard inputs or outputs.