GraphflowDB Coding Style

This is a document for our cpp coding style. The goal of this document is to make sure that our styles inside the codebase are consistent, and these style rules exist to keep the codebase manageable as time goes by and the team grows. This document should be used as a reference whenever someone in the team is not sure about a piece of code satisfying the style or not, and we also use this document to solve conflicts between different styles in our existing codebase. This document references Google C++ Style Guide

Header files

In general, every .cpp file should have an associated .h file, and we use .h instead of .hpp in our codebase. There are some common exceptions that no .h files are associated, such as unit tests and small .cc files containing just a main() function.

A header file should follow the following template:

#pragma once

#include <xxx>

#include “yyy”

namespace nnn {

Class ccc {}

} // namespace nnn

The header file starts with #pragma once as the first line with an empty line afterwards. Then the header file goes with #include statements. Finally, main content is wrapped inside namespace {}, and notice that we always keep an empty line after the inner most namespace {.

Namespace

Function Declarations in header files

Functions in header files should only contain declarations without implementations, except for following cases:

• The function is inlined.
• The function is a template function.
• The function is an empty constructor with only initializer list and possibly assert statements.

In-line Functions

Define functions inline only when they are very small, usually 1 or 2 lines, and shouldn’t be larger than 5 lines.

Forward Declaration

Classes

Structs vs. Classes

Use a struct only for passive objects that carry data; everything else is a class.

Structs vs. Pairs and Tuples

Prefer to use a struct instead of a pair or a tulle whenever the elements can have meaningful names. While using pairs and tuples can avoid the need to define a custom type, potentially saving work when writing code, a meaningful field name will almost always be much clearer when reading code than .first, .second, or std::get<X>. While C++14's introduction of std::get<Type> to access a tuple element by type rather than index (when the type is unique) can sometimes partially mitigate this, a field name is usually substantially clearer and more informative than a type. Pairs and tuples may be appropriate in generic code where there are not specific meanings for the elements of the pair or tuple. Their use may also be required in order to interoperate with existing code or APIs.

Ownership and Smart Pointers

Types

Use of const

Use of constexpr

Naming

Class names

Variable names

Function names

Comments

TODOs

TODOs should include the string TODO in all caps, followed by the name, bug ID, or other identifier of the person or issue with the best context about the problem referenced by the TODO. The main purpose is to have a consistent TODO that can be searched to find out how to get more details upon request. A TODO is not a commitment that the person referenced will fix the problem. Thus when you create a TODO with a name, it is almost always your name that is given.

// TODO(Zeke) change this to use relations.
// TODO(bug 12345): remove the "Last visitors" feature.

Exceptions

Bazel