Developer Notes

Style Guide

Please check your code for style issues by running

make format

which uses clang-format. All style fixes provided by make format should be committed.

In addition to those automatically enforced style rules, Ratel tends to follow the following code style conventions:

  • Variable names: snake_case

  • Struct members: snake_case

  • Function names: PascalCase

  • Type names: PascalCase

  • Constant names: CAPS_SNAKE_CASE

Also, documentation files should have one sentence per line to help make git diffs clearer and less disruptive.

Clang-tidy

Please check your code for common issues by running

make tidy

which uses the clang-tidy utility included in recent releases of Clang. This tool is much slower than actual compilation (make -j parallelism helps). All issues reported by make tidy should be fixed.

Header Files

Header inclusion for source files should follow the principal of ‘include what you use’ rather than relying upon transitive #include to define all symbols.

Every symbol that is used in the source file foo.c should be defined in foo.c, foo.h, or in a header file #included in one of these two locations. Please check your code by running the tool include-what-you-use to see recommendations for changes to your source. Most issues reported by include-what-you-use should be fixed; however this rule is flexible to account for differences in header file organization in external libraries.

Header files should be listed in alphabetical order, with installed headers preceding local headers.

#include <ceed.h>
#include <petsc.h>
#include <stdbool.h>
#include <string.h>

#include "include/ratel.h"

restrict Semantics

QFunction arguments can be assumed to have restrict semantics. That is, each input and output array must reside in distinct memory without overlap.

Continuous Integration (CI) and Testing

Whenever a merge request is created, the Ratel test suite is run against a variety of hardware and software configurations. If one of the tests in the CI pipeline fails, you should look at the error in the CI job log. The log will provide the command which failed and relevant details (such as diff output) to help debug the issue. You can also see the CGNS or CSV output of a failed run, if applicable, by selecting “Download” on the Job Artifacts (to the right of the log). Artifacts from failed runs will be contained in the test_failure_artifacts folder inside the artifacts archive.