C++

Follow the guidelines below when writing and updating C++ files.

Automated linting

As mentioned in the overview, where possible, we have automated linting processes, so you need not remember all the guidelines perfectly. For C++, we currently use the following tools:

• clang-format for formatting (base config)

• clang-tidy for static analysis (base config)

When the linter disagrees with a guideline, err on the side of following the linter, since:

• we don’t want automated runs of the linters to fail, leading to them being ignored due to the noise.

• the linter may have a good reason for disagreeing with the guideline.

• the linter’s configuration may be more up-to-date than the guideline.

Tip

To learn about how to apply the linters to a new C++ project, see here.

When you encounter such a disagreement, if it hasn’t been noted below, please open an issue to track it.

Guidelines

We adhere to Google’s C++ style guide (as of 8f97e24) with the following exceptions (organized according to the sections in Google’s style guide).

Note

This section is a work in progress and does not yet include all exceptions after the Classes section of Google’s style guide.

Header files

Self-contained Headers

• Header files should end in .hpp.

• Don’t use non-header files meant for inclusion (e.g., .impl/.inc/.tpp files included at the end of the .hpp file), since they can confuse static analysis tools.

The #define Guard

The symbol name should have the form

<NAMESPACE>_<FILENAME-STEM>_<FILENAME-EXTENSION>

where

• <NAMESPACE> is the namespace of the file.

  • For files in a nested namespace, each namespace layer should be separated by an underscore.

• <FILENAME_STEM> is the file’s name without the extension.

  • For stems with multiple words, the words should not be separated with underscores.

• <FILENAME_EXTENSION> is the file’s extension.

For example:

clp/streaming_archive/reader/SegmentManager.hpp

#ifndef CLP_STREAMING_ARCHIVE_READER_SEGMENTMANAGER_HPP
#define CLP_STREAMING_ARCHIVE_READER_SEGMENTMANAGER_HPP

namespace clp::streaming_archive::reader {
    // ...
}

#endif  // CLP_STREAMING_ARCHIVE_READER_SEGMENTMANAGER_HPP

Names and order of includes

• For codebases where the code is not organized into well-defined libraries, it is fine to use UNIX directory aliases to include headers.

• For C headers that have C++ counterparts (e.g., stddef.h vs cstddef), use the C++ counterpart.

Scoping

Namespaces

Single-line nested namespace declarations (e.g. bar in foo) should use the following format (unless doing so would affect clarity):

namespace foo::bar {
}

Internal linkage

Only use unnamed namespaces (instead of the static qualifier) to give functions and variables internal linkage. However, as Google’s style guide indicates, you can’t use unnamed namespaces in header files. For symbols that should only be used within a header file, you can create a named namespace in the header file, where its name is of the form:

<FilenameStem>_internal

where

• <FilenameStem_stem> is the file’s name without the extension.

• _internal is a fixed suffix indicating the namespace’s purpose.

For example:

clp/streaming_archive/reader/SegmentManager.hpp

namespace clp::streaming_archive::reader {
namespace SegmentManager_internal {
// Internal symbols
}
}

Classes

Doing work in constructors

We allow (but discourage) the use of exceptions, even in constructors. If creating an object can fail, you’re encouraged to use a factory function that performs the work that can fail, and then returns a result containing an error code if unsuccessful or the object if successful.

Declaration order

Within each section, order declarations as follows:

1. Types and type aliases (typedef, using, enum, nested structs and classes, and friend types).

2. Static constants.

3. Static functions:

   • Factory functions.

   • Other functions.

4. Static variables.

5. Constructors.

6. Copy & move constructors and assignment operators.

7. The destructor.

8. Methods (member functions):

   • Overridden methods.

   • Implemented abstract methods.

   • All other methods.

9. Data members.

The differences between our declaration order and the order in Google’s style guide is to conform with our general ordering guidelines.