Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# 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.