Skip to content

Coding Guidelines

Basics

  • Better to commit too much than not often enough
  • Better to have more comments than less (you will have to return to your code at one point)
  • All the code should follow the same styleguide
  • Make sure there is always environment file, package and Python versions as essential for reproducibility
  • DRY principle: Do not repeat yourself!
  • Know the basics of OOP
  • Write modular code, it will save you a lot of time in the future

Design Patterns

Review common design patterns at https://refactoring.guru/design-patterns/catalog

Package Development

Template and Setup:

  • Use our package template: https://github.com/lamalab-org/LamaBlueprint
    • Create a package with: 
      uvx cookiecutter https://github.com/lamalab-org/LamaBlueprint.git
      or 
      pip install --user cookiecutter
cookiecutter https://github.com/lamalab-org/LamaBlueprint.git
  • Dependency management: uv
  • Virtual environments: Always use them

Code Quality:

  • Formatting and linting: ruff
    • Pre-commit hooks: with the group template a pre-commit configuration file is included. To run it with every commit, install the pre-commit package and run pre-commit install.
  • Logging: loguru
  • Testing: pytest with continuous integration on GitHub

Documentation:

  • Framework: Diataxis with mkdocs
  • Docstrings: Explain why, not what—the code shows what, but not why

Best Practices

Styleguide

  • It is important to keep the code well documented and formatted.
  • Classes and functions should have explanations and varaibles meaningful name. For dos and dont's check the google styleguide
  • Use typing and declare the function variable types and returns

Performance:

  • Cache expensive function calls when arguments repeat
  • Use pathlib for cross-platform file paths—never string concatenation

Testing:

Follow the Turing Way Guide's "Code Testing" and "Continuous Integration" sections for comprehensive guidance.

Some useful commands

Draco cluster: 

# Interactive GPU session
salloc --partition=gpu-test --time=10 --gres=gpu:1

# List jobs
squeue -o "%.8i %.9P %.10j %.8u %.8T %.8M %.12l %.6D %R %S" -u $USER

Debugging: 

import pdb; pdb.set_trace()  # or breakpoint() in Python 3.7+

# To disable all breakpoints:
pdb.set_trace = lambda: None

Conda issues: 

conda clean -i  # fixes JSONDecodeError

Resources