Code style conventions¶
It is important to keep a consistent formatting of the C++ and Python code
to avoid hard-to-read diffs and merge conflicts.
clang-format and yapf can be used to format C++ and Python code,
respectively, according to a predefined style file.
PSI4 provides the psi4/.clang-format and psi4/.style.yapf files in the root
folder of the project.
It is recommended that modifications and/or new files checked into the
repository are formatted according to these style files using
yapf. It is then helpful if these tools be part of your development toolchain.
yapf are installed, there are three ways in which
formatting of the code can be accomplished, in decreasing order of automation:
By integrating the formatters into your editor.
By installing Git hooks to run the formatters when committing.
By running the formatters manually on the modified files.
How to impose code style through your editor¶
yapf can be integrated into widely used editors.
The Neoformat plugin can be configured
to format files when saving them to disk.
How to impose code style through Git hooks¶
Git hooks are scripts that are run before or after certain Git events.
In this particular case, we want to make sure that all files that have been
added to the staging area with
git add are formatted according to the style
before they committing them with
The hook to be modified is then the pre-commit hook.
PSI4 uses the pre-commit framework, with configuration file psi4/.pre-commit-config.yaml.
To take advantage of pre-commit hooks, you will need to install the
pip install pre-commit
or using Conda:
conda install pre_commit -c conda-forge
Finally, you need to install the actual hooks:
Pre-commit hooks will be run on every
git commit, but the
option can be used to skip their execution.
Hooks are powerful, but integrating the formatter into your editor will prove to be better. Hooks need to be installed anew for every fresh clone of the repository you are working on.
How to run code-style tools clang-format and yapf manually¶
The least recommended approach to formatting your code is to run manually the formatters. The following commands will format only the files that have been modified:
clang-format -style=file -i git diff –relative –name-only HEAD – *.cc *.h yapf -i git diff –relative –name-only HEAD – *.py
How and when to not apply code styling to your contributions¶