Code style

All code in GSD must follow a consistent style to ensure readability. We provide configuration files for linters (specified below) so that developers can automatically validate and format files.

These tools are configured for use with pre-commit in .pre-commit-config.yaml. You can install pre-commit hooks to validate your code. Checks will run on pull requests. Run checks manually with:

pre-commit run --all-files

Python

Python code in GSD should follow PEP8 with the formatting performed by yapf (configuration in setup.cfg). Code should pass all flake8 tests and formatted by yapf.

Tools

• Linter: flake8

  • With these plugins:

    • pep8-naming

    • flake8-docstrings

    • flake8-rst-docstrings

  • Configure flake8 in your editor to see violations on save.

• Autoformatter: yapf

  • Run: pre-commit run --all-files to apply style changes to the whole repository.

Documentation

Python code should be documented with docstrings and added to the Sphinx documentation index in doc/. Docstrings should follow Google style formatting for use in Napoleon.

C

• Style is set by clang-format=11

  • Whitesmith’s indentation style.

  • 100 character line width.

  • Indent only with spaces.

  • 4 spaces per indent level.

  • See .clang-format for the full clang-format configuration.

• Naming conventions:

  • Functions: lowercase with words separated by underscores function_name.

  • Structures: lowercase with words separated by underscores struct_name.

  • Constants: all upper-case with words separated by underscores SOME_CONSTANT.

Tools

• Autoformatter: clang-format.

• Linter: clang-tidy

  • Compile GSD with CMake to see clang-tidy output.

Documentation

Documentation comments should be in Javadoc format and precede the item they document for compatibility with Doxygen and most source code editors. Multi-line documentation comment blocks start with /** and single line ones start with ///.

See gsd.h for an example.

Restructured Text/Markdown files

• 80 character line width.

• Use spaces to indent.

• Indentation levels are set by the respective formats.

Other file types

Use your best judgment and follow existing patterns when styling CMake and other files types. The following general guidelines apply:

• 100 character line width.

• 4 spaces per indent level.

• 4 space indent.

Editor configuration

Visual Studio Code users: Open the provided workspace file (gsd.code-workspace) which provides configuration settings for these style guidelines.