Code quality and style - cma-open/cmatools GitHub Wiki

Standards and process

• Code will follow an agreed code style format to facilitate code review (by allowing users to focus on code function not style)
• Code will be automatically formatted for style via the auto formatter black (called via pre-commit, can be called maually via a script or via github workflows)
• Code will be modular to aid maintenance and code review
  • Suitable modular limits will be subject to refinement within the dev team
  • Prompts via PyCharm Code Inspect will identify excessive numbers of parameters
  • Maximum lines per function (40) and module (500) will be used to recommend refactoring to aid modularity and ease of review
• Code will be well commented, self-describing (descriptive variable and function names) and will have docstrings
• Code will follow Python PEP8
• Code will follow Python PEP257 for docstrings
• Docstrings will follow the Numpy format
  • https://numpydoc.readthedocs.io/en/latest/format.html
  • https://numpydoc.readthedocs.io/en/latest/example.html#example
  • https://numpydoc.readthedocs.io/en/latest/install.htm
  • There are various options for numpy style documentation, therefore a consistent subset of these were selected, these are documented in an example subpackage within this repo
    • src/cmatools/examplesubpackage/example_cmatools.py
    • this follows the example of key python packages such as pandas and xarray in the way e.g. that classes are documented
    • e.g.
      • https://github.com/pydata/xarray/blob/main/xarray/core/dataset.py#L577-L7731
      • https://github.com/pandas-dev/pandas/blob/v1.3.4/pandas/core/frame.py#L456-L10751

Automation and pre-commits

• The project uses pre-commits to automatically format code style and format
• The following packages and configurations are used
  • pre-commit: configured via the .pre-commit-config.yaml file
  • black: code style and formatting tool
  • isort: sorts imports alphabetically, and automatically separates into sections and by type. Configured via pyproject.toml
  • flake8: code linter to check for syntax errors, possible bugs, stylistic errors

Maintenance

• The code formatters require regular checks to update the tool vesions as upgrades are released