Coding Style Guide

Collaboration on a coding project like migrid becomes easier if some basic coding style rules are agreed on and followed consistently. This helps limiting e.g. code changes in pull requests to the actual functionality without a lot of minor non-functional changes.

We have developed some rules of thumb over the years and are still working on getting them formalized as a complete coding style guide here. PEP 8 is a good base and should generally be followed for everything not explicitly covered here, as should the related PEP 257 for doc strings. We aim for documenting our code to the extent where it is always easy to figure out what a module, function/method or class does. Importantly that should also be the case for colleagues who didn't write the code or just wrote it long time ago. Therefore, please always include module level, class and function/method doc strings. Extremely simple functions where the name says it all can be excused from this rule, but if in doubt at all please just add one.

We generally aim for line length of at most 80 characters to ease readability in most editors, no matter if they run locally or in a shell on remote systems. The formatting and linting tools we rely on typically have a specific flag or setting to keep with that choice.

One can optionally use the black format helper to follow a style compatible with most of our style rules, but then it's needed to tell it to adjust line length and adjust module imports to our hanging indents afterwards, as black itself takes the firm stance of not allowing such style tweaking. Still, this adjustment is easy to do with the isort utility after running black.

As an example on can do that for the mig/server/grid_janitor.py script with:

black --line-length=80 mig/server/grid_janitor.py
python3 -m isort mig/server/grid_janitor.py -m=HANGING_INDENT --line-length=80

Other helpers for checking coding style include pylint and flake8. They tend to be somewhat too verbose with the default settings so one might want to filter warnings as we do in our Github sanity check and stylecheck actions.