Good Coding Practices¶
Packages and Environment¶
We provide an environment yaml file for creating an envirnoment with all the packages you need to use CLEO (to use PySD, to build the documentation, or to run pre-commit etc.).
The easiest way to use it is to create a new Conda or Mamba environment, e.g.
$ conda env create --file=environment.yml
or
$ mamba env create --file=environment.yml
And then activate this environment everytime you use CLEO, e.g.
$ conda activate cleoenv
We kindly ask that you also contact us or open a new issue on our GitHub repository if you discover this environment is missing any packages.
Pre-Commit¶
We use pre-commit to check our code for simple issues before submission to code review, such as before pushing to a GitHub repository. We reccomend you use it too.
Pre-Commit has “hooks” which can be used for a vast range of measures to ensure you follow good coding practices. For example, we use pre-commit to find and correct mistakes such as missing semicolons, trailing whitespaces, bad indentations etc., and to ensure we conform to our chosen code style guide.
You can learn more by checking out pre-commit’s comprehensive documentation.
In case you want to use our pre-commit hooks, first load your environment with pre-commit installed, then install the pre-commit hooks, e.g.
$ pre-commit install
Pre-commit should then run automatically upon `git commit.
Commit Specification¶
We use conventional commits as a a lightweight convention on top of commit messages to ensure they are meaningful, provide a useful history and can be used by automated tools such as Cocogitto-bot.
Code Style / Formatting¶
For Python, we use ruff <https://docs.astral.sh/ruff/>`_ for formatting and linting. Ruff checks are something like the combination of several Python linters (Flake8, isort, pydocstyle etc.) and the black formatter. We obey the default settings of ruff except we ignore E402 errors.
- For C++ we obey the Google C++ Style Guide with:
- IndentWidth: 2TabWidth: 2UseTab: NeverColumnLimit: 100