Souffle style guide

Souffle Style Guide

Souffle's style is generally similar to the Google C++ style guide, with similar reasoning, bar the following exceptions.

Header files

All header files are protected with #pragma once.

Header files should include only required headers, and all headers needed. Do not assume that transitively included header files will always be transitively included. Note that a header file for a class that extends another can be assumed to already have any headers required for the interface.

Use standard include order for readability and to avoid hidden dependencies: Related header, your project's .h files, other libraries' .h, C++ library, C library. Use C++ headers instead of their C counterparts (cstddef vs stddef.h)

Forward declarations should be used for non-system classes, where possible.

Initialisation

Initialise all member variables. Do not instead rely on code accessing the variables in the intended manner.

64-bit portability

Souffle specifically allows defining its default domain, RamDomain, as either 32 bit or 64 bit, and should remain agnostic. Do not rely on it being equivalent to an int.

auto

Use auto to avoid declaring a type twice. auto is also preferred as an alternative to overly long and unhelpful names, such as when using namespaces and templates. Note that if the type is important to understanding a variable and the type is hidden by the use of auto consider specifying the type rather than using auto.

using

Prefer using to typedef

Naming

In general, use camelcase for names. Class and template variables should be capitalised. Names should be descriptive. Readability by a new developer is more important than quicker typing.

File names for Soufflé classes should be capitalised. File names for non-Soufflé-specific classes may differ to allow a more generalised consistency.

Comments

Doxygen comments should be used for all files and classes. Methods should be fully commented unless their intent and use is already documented by types and naming. Every file should contain licence boilerplate.

Unclear code should be documented. Tricky or complicated code should be explained with a brief comment before it. Avoid end of line comments. If end of line comments are needed they should be kept very brief. Do not add comments that merely repeat the code.

Formatting

A single indent level is 4 spaces. Line length will be less than 110 characters.

UTF-8 formatting is used - but non-ASCII characters should be used rarely.

Control flow

Use braces even for single line flows for consistency and readability. Avoid deep nesting. Exit a function early rather than wrap the entire contents in an if. e.g.

if (!condition) {
    return false;
}
// stuff

rather than

if (condition) {
    // stuff
}

Booleans

Avoid implicit casting to and from booleans. Pointers will be compared with nullptr rather than false.

clang-format

The basics of Souffle's style can be checked automatically using clang-format and the included .clang-format file.

clang-tidy

A .clang-tidy file is also included. These tests demonstrate the preferred style, but are not required and may change. The current tests may be too strict, or are of questionable utility.