Code Style Guidelines

In this page, you can find the coding guidelines to contribute to the project. Even though some of these may seem difficult and not worthy it, making the contributions look-a-like and predictable does wonders in the code review tasks.

1. Use Black so we don't have to discuss code style.
   • Multiple text editors / IDEs support Black already.
   • Run pre-commit install after you install developer requirements to use pre-commit (it runs black, ruff and two other pre-commit hooks for you on every new commit).
2. Use Python 3's f-strings to format strings all the time. Prettier and nicer to understand.
   • Except when using the logging framework to log errors or exceptions. In those cases, keep the old printf ("%s", foo) style, passing the variables as arguments. This helps grouping errors in application performance monitoring tools.
   • This applies specifically to self.log_exception() and self.log_error() calls in commands.
   • The other log calls (self.log, self.log_warning and the same with logging) are optional because these print to stdout only.
3. Never use bare except:. Always use a specific exception or as last resort except Exception:
   • Inside an exception block, use logger.exception() or self.log_exception(). Avoid log_error because the full stack trace will not be used.
   • There's no need to catch exceptions with exception Exception as e when calling log_exception because the exception context is automatically sent.
4. Avoid import *. Follow PEP 8 and/or use isort.
5. Never push code or files that contain sensitive data in them, whether that's passwords, tokens, API keys, personal identifiable information and so on. Case in point, never push your local.env to GitHub, nor store secrets in GitHub code (maybe in GitHUb's native secret's manager, if that's your choice).
6. Write code comments to explain the why or explain what is not obvious. Do not overuse them.
7. Write unit tests. We use pytest.
   • Long term goal: have high coverages in the future and start writing some integration and end-to-end tests.
8. Use type hints if you are feeling adventurous.
   • Long term goal: run mypy on Surface code and enforce no errors.