Coding conventions

Module naming

Subdirectories of src contain modules. The first component of a module name is the type of module it is, either sig for digital signatures, or kem for a key encapsulation method.

Public functions are intended to be used by calling applications/libraries, and are exported in .h files. Public functions start with upper-case letters and take the form OQS_KEM_... or OQS_SIG_....
Private functions that still have global scope are functions which might be meaningful on their own, and could be useful to another research, but are not generally intended to be used by calling applications/libraries. They might be tested independently by a test hardness. Private functions with global scope start with lower-case letters and are of the form oqs_sig_... or oqs_kem_....
Private functions that do not have global scope can be named in any way. However, they must be declared static to avoid polluting the global namespace. The test_namespace test in the test suite will report any non-namespaced symbols.

We use C11. At the very least, the code should compile cleanly—without warnings—with the compiler flags listed here.

Memory involving secrets (secret keys, derived shared secrets) should be explicitly zeroed-out once it is no longer required. OQS_MEM_cleanse should be used to zero-out memory on the stack; OQS_MEM_secure_free should be used to zero-out and deallocate memory on the heap. Note that you should use one of these two instead of directly calling memset or bzero: an optimizing compiler may optimize out the seemingly "unnecessary" call to be memset or bzero, whereas we have taken steps in our two functions to prevent that from happening.
Memory access patterns and runtime should be independent of secret data (i.e., "constant time").
Code must pass clang's AddressSanitizer, which is run on nightly builds.

To indicate success/failure, functions should return the type OQS_STATUS, which is an enum defined in src/common/common.h. New error codes can be added for distinguishing new error types as required. New error codes should have numbers manually assigned to them (for consistency over time as new errors are added), and should be grouped (eg., reserve -100..-199 for errors related to some Algorithm A, -200..-299 for errors related to some Algorithm B, etc.).
Callers should compare with the symbol rather than the individual value. For example,

ret = OQS_KEM_encaps(...);
if (ret == OQS_SUCCESS) { ... }

Source code should be formatted using the {ninja|make|nmake} prettyprint target before committing. We use astyle for consistent formatting with the formatting options indicated in .astylerc. All .c and .h files must meet the formatting requirements, except for files in directories names external or pqclean_.... The test_style test in the test suite will report any formatting violations.
Tabs are used for indentation.
Lines can be arbitrarily long and are not limited to 80 characters.
Braces for function definitions, if statements, and for loops open on the same line as the function definition/if statement/for loop.
Our goal is to work towards the Misra C guidelines.

Inline documentation in .c and .h files is done using Doxygen.
Public APIs must be documented using Doxygen.
All files (except those in external or pqclean directories) must include a machine-readable SPDX-License-Identifier header in a comment, as described by https://spdx.org/ids