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 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.
- Linter: flake8
- With these plugins:
- 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.
- Run:
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.
- 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
.
- Functions: lowercase with words separated by underscores
- Autoformatter: clang-format.
- Linter: clang-tidy
- Compile GSD with CMake to see clang-tidy output.
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.
- 80 character line width.
- Use spaces to indent.
- Indentation levels are set by the respective formats.
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.
Visual Studio Code users: Open the provided workspace file (gsd.code-workspace
) which provides configuration settings for these style guidelines.