2. Style Guidelines

Important

To ensure consistent styling with little effort, this project uses clang-format. The repository contains a .clang-format file that can be used to automatically apply the style rules that are described below. The easiest way to use clang-format is through a plugin/extension for your editor/IDE that automatically runs clang-format using the .clang-format file whenever a file is saved.

Follow the C++ Core Guidelines except when they conflict with another guideline listed here.

Conform to the C++14 standard.

2.1. Indentation

Use two spaces per indentation level.

2.2. Source Files

Use a .cpp suffix for code files and .h for header files.

Header files should always use include guards with the following style (See SF.8):

#ifndef ENRICO_MODULE_NAME_H
#define ENRICO_MODULE_NAME_H

namespace enrico {
...
content
...
}

#endif // ENRICO_MODULE_NAME_H

Avoid hidden dependencies by always including a related header file first, followed by local includes, other library includes, and then C/C++ library includes. For example:

// foo.cpp
#include "foo.h"

#include "bar.h"
#include "baz.h"

#include <gsl/gsl>

#include <cstddef>
#include <iostream>
#include <vector>

2.3. Naming

Struct and class names should be CamelCase, e.g. HexLattice.

Functions (including member functions) should be lower-case with underscores, e.g. get_indices.

Local variables, global variables, and struct/class member variables should be lower-case with underscores, except for physics symbols that are written differently by convention (e.g., E for energy). Data members of classes additionally have trailing underscores (e.g., a_class_member_).

All classes and non-member functions should be declared within the enrico namespace.

Accessors and mutators (get and set functions) may be named like variables. These often correspond to actual member variables, but this is not required. For example, int count() and void set_count(int count).

Variables declared constexpr or const that have static storage duration (exist for the duration of the program) should be upper-case with underscores, e.g., SQRT_PI.

Use C++-style declarator layout (see NL.18): pointer and reference operators in declarations should be placed adjacent to the base type rather than the variable name. Avoid declaring multiple names in a single declaration to avoid confusion:

T* p; // good
T& p; // good
T *p; // bad
T* p, q; // misleading

2.4. Source Annotation

Classes, structs, and functions are to be annotated for the Doxygen documentation generation tool. Use the \ form of Doxygen commands, e.g., \brief instead of @brief.