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

Code Review and Pull Requests

All significant code changes go through pull requests with at least one human reviewer. PRs should be small enough to review in one sitting. No code should pile up locally — push frequently, open draft PRs early. We use monthly pod partners as default reviewers.

When PRs exceed 1,000 changes across dozens of files, they become challenging to review thoroughly — requiring half a day or more of focused attention. Even when changes are thematically grouped, splitting them into smaller PRs makes the review process more manageable and gets your work merged faster. This helps both reviewers and you.

This applies to all shared repositories, research code that others depend on, and any public-facing project. For exploratory notebooks and throwaway scripts, use your judgment — but when in doubt, open a PR.

AI-Assisted Code

If you used AI to write code, make sure you can explain every part of it. If you can't walk someone through what your code does and why, you need to understand it before moving on.

AI tools are useful for acceleration, not for replacing understanding. The code has your name on it — own it. Use your pod sessions to probe each other on understanding: Can you explain what this function does? Why this design choice? What happens at edge cases? Expect Kevin to do the same — he will ask you about the details of your code, and you should be able to discuss them fluently.

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