ALICE O² C++ Coding Guidelines

Hooray! Now you know you can expand points to get more details. Alternatively, there are an "expand all summaries" and an "expand all summaries and extra details" at the top of this document.

To guarantee uniqueness, they should be based on the full path in a project's source tree. For example, the file foo/src/bar/myFile.h in project foo should have the following guard:

#ifndef FOO_BAR_MYFILE_H_
#define FOO_BAR_MYFILE_H_

...

#endif  // FOO_BAR_MYFILE_H_

Definition: A "forward declaration" is a declaration of a class, function, or template without an associated definition. #include lines can often be replaced with forward declarations of whatever symbols are actually used by the client code.

Pros:

• Unnecessary #includes force the compiler to open more files and process more input.
• They can also force your code to be recompiled more often, due to changes in the header.

Cons:

• It can be difficult to determine the correct form of a forward declaration in the presence of features like templates, typedefs, default parameters, and using declarations.
• Forward declaring multiple symbols from a header can be more verbose than simply including the header.
• Forward declarations of functions and templates can prevent the header owners from making otherwise-compatible changes to their APIs; for example, widening a parameter type, or adding a template parameter with a default value.
• Forward declaring symbols from namespace std:: usually yields undefined behavior.

Decision:

• When using a function declared in a header file, always #include that header.
• When using a class template, prefer to #include its header file.
• When using an ordinary class, relying on a forward declaration is OK, but be wary of situations where a forward declaration may be insufficient or incorrect; when in doubt, just #include the appropriate header.
• Do not replace data members with pointers just to avoid an #include.

Definition:

The inline keyword indicates that inline substitution of the function body at the point of call is to be preferred to the usual function call mechanism. But a compiler is not required to perform this inline substitution at the point of call.

Functions that are defined within a class definition are implicitly inline.

An inline function must be defined in every translation unit from where it is called. It is undefined behavior if the definition of the inline function is not the same for all translation units. Note that this implies that the function is defined in a header file. This can have an impact on compile time and lead to longer (= less efficient) development cycles.

Note that the inline keyword has no effect on the linkage of a function. Linkage can be changed via unnamed namespaces or the static keyword.

Decision:

If you add a new function, put it into the .cxx file per default. Small functions, like accessors and mutators may be placed into the .h file instead (inline). Also, most template function implementations need to go into the .h file. If you later determine that a function should be moved from the .cxx file into the .h file, please make sure that it helps the compiler in optimizing the code. Otherwise you're just increasing compile time.

There are two types of #include statements: #include <myFile.h> and #include “myFile.h”.

• Include headers from external libraries using angle brackets.

  #include <iostream>
  #include <QtCore/QDate>
  #include <zlib.h>

• Include headers from your own project using double quotes.

  #include "MyClass.h"

The header files of external libraries are obviously not in the same directory as your source files. So you need to use angle brackets.

Headers of your own application have a defined relative location to the source files of your application. Using double quotes, you have to specify the correct relative path to the include file.

Another important aspect of include management is the include order. Typically, you have a class named Foo, a file Foo.h and a file Foo.cxx . The rule is : In your file Foo.cxx, you should include Foo.h as the first include, before the system includes.

The rationale behind that is to make your header standalone.

Let's imagine that your Foo.h looks like this:

class Foo
{
 public:
  Bar getBar();
}

And your Foo.cpp looks like this:

#include "Bar.h"
#include "Foo.h"

Your Foo.cxx file will compile, but it will not compile for other people using Foo.h without including Bar.h. Including Foo.h first makes sure that your Foo.h header works for others.

// Foo.h
#include "Bar.h"
class Foo
{
 public:
  Bar getBar();
}

// Foo.cxx
#include "Foo.h"

For more details: Getting #includes right.

Example of a typical class definition within a project and sub-project namespace:

namespace project::subproject
{

class MyClass
{
...
};

} // namespace subproject::project

Alternatively, the C++98/11/14 style for nested namespaces can be used:

namespace project
{
namespace subproject
{

class MyClass
{
...
};

} // namespace subproject
} // namespace project

A nonmember function that is logically tied to a specific type should be in the same namespace as that type.

# include "Bar.h"
// OK in .cxx after include statements
using namespace foo;

// sometimes a using declaration is preferable, to be precise
// about the symbols that get imported
using Foo::Type;

// Forbidden in .h -- This pollutes the namespace.
using namespace foo;

Extra details and exceptions to the rules:

Definition: All symbols inside an unnamed namespace (sometimes also called anonymous namespace) will have internal linkage. Thus, it is impossible to access these objects from other translation units (.cxx files).

Pros: Because of the internal linkage it is easier to reason about the code. This can lead to better optimization from compilers and clearer encapsulation.

Decision: Use unnamed namespaces in .cxx files whenever possible.

namespace project 
{
namespace                            // This is in a .cxx file.
{
int someFunction(int value) { return value + 1; }
}  // unnamed namespace

void someOtherFunction() 
{
  int value = 0;
  value = someFunction(value);
  ...
}
}

Extra details and exceptions to the rules:

// Shorten access to some commonly used names in .cxx files.
namespace fbz = ::foo::bar::baz;
 
// Shorten access to some commonly used names (in a .h file).
namespace librarian 
{
  // The following alias is available to all files including
  // this header (in namespace librarian):
  // alias names should therefore be chosen consistently
  // within a project.
  namespace pds = ::pipeline_diagnostics::Sidetable;

  inline void myInlineFunction() {
    // namespace alias local to a function (or method).
    namespace fbz = ::foo::bar::baz;
    ...
  }
}  // namespace librarian

Note that an alias in a .h file is visible to everyone including that file, so public headers (those available outside a project) and headers transitively included by them, should avoid defining aliases, as part of the general goal of keeping public APIs as small as possible.

Declaring entities in namespace std represents undefined behavior, i.e., not portable. To declare entities from the standard library, include the appropriate header file.

Putting nonmember functions in a namespace avoids polluting the global namespace. Static member functions are an alternative as long as it makes sense to include the function within the class.

namespace mynamespace 
{
void doGlobalFoo(); // Good -- doGlobalFoo is within a namespace.
  
class MyClass 
{
 public: 
  ...
  // Good -- doGlobalBar is a static member of class MyClass and 
  // has a reason to be part of this class (not shown here).
  static Bar* doGlobalBar();
}

Variables whose lifetime are longer than necessary have several drawbacks:

• They make the code harder to understand and maintain.
• They can't be always sensibly initialized.

Extra details and exceptions to the rules:

Do not separate initialization from declaration, e.g.

int value;
value = function();      // Bad -- initialization separate from declaration.

int value = function();  // Good -- declaration has initialization.

Use a default initial value or ? to reduce mixing data flow with control flow.

int speedupFactor;       // Bad: does not initialize variable
if (condition) {
  speedupFactor = NoFactor;
}
else {
  speedupFactor = DoubleFactor;
}

int speedupFactor = DoubleFactor; // Good: initializes variable
if (condition) {
  speedupFactor = NoFactor;
}

int speedupFactor = condition ? NoFactor : DoubleFactor; // Good: initializes variable

Prefer declaration of loop variables inside a loop, e.g.

int i;                   // Bad: does not initialize variable
for (i = 0; i < number; ++i) {
  doSomething(i);
}

for (int i = 0; i < number; ++i) {
  doSomething(i); // Good
}

In C++11, the brace initialization syntax for builtin arrays and POD structures has been extended for use with all other datatypes.

Example of brace initialization:

std::vector<std::string> myVector{"alpha", "beta", "gamma"};

Example of single-argument assignments:

int value = 3;                           // preferred style
std::string name = "Some Name"; 
  
int value { 3 };                         // also possible
std::string name{ "Some Name" }; 
std::string name = { "Some Name" };

User data types can also define constructors that take initializer_list, which is automatically created from braced-init-list:

#include <initializer_list>
class MyType 
{
 public:
  // initializer_list is a reference to the underlying init list,
  // so it can be passed by value.
  MyType(std::initializer_list<int> initList) {
    for (int element : initList) { .. }
  }
};
MyType myObject{2, 3, 5, 7};

Finally, brace initialization can also call ordinary constructors of data types that do not have initializer_list constructors.

// Calls ordinary constructor as long as MyOtherType has no
// initializer_list constructor.
class MyOtherType 
{
 public:
  explicit MyOtherType(std::string name);
  MyOtherType(int value, std::string name);
};
MyOtherType object1 = {1, "b"};
// If the constructor is explicit, you can't use the "= {}" form.
MyOtherType object2{"b"};

Never assign a braced-init-list to an auto local variable. In the single element case, what this means can be confusing.

auto value = {1.23};        // value is an initializer_list<double>

auto value = double{1.23};  // Good -- value is a double, not an initializer_list.

For clarity of the examples above we use directly explicit values, however following the rule about magic numbers requires to define all such numbers as named constants or constexpr first.

Definition: A global variable is a variable that can be accessed (theoretically) from everywhere in the program. The adjective "global" should rather be understood as concerning its linkage, not whether it is in the global scope.

int gBar;           // this is obviously global
class Something
{
 private:
  static int sId; // but this one too (details at the end of the rule)
};
namespace notglobalscope 
{
  Foo fooObject;    // and finally this one as well
}

Pros: Global variables are a simple solution to sharing of data.

Cons: Global variables make it harder to reason about the code (for humans and compilers): the smaller the number of variables a given region of code reads and writes, the easier. Global variables can be read and written from anywhere. Therefore, global variables pose a challenge to the optimizer.

Decision: We want to reduce the shared data in our software to the unavoidable minimum. Therefore, global variables should be avoided where other means of communication are possible.

Extra details and exceptions to the rules:

Definition:

• This rule additionally applies to file-static variables.
• A global variable is statically initialized if the type has no constructor or a constexpr constructor. This is the case for fundamental types (integers, chars, floats, or pointers) and POD (Plain Old Data: structs/unions/arrays of fundamental types or other POD structs/unions).

Pros: Dynamic initialization of globals can be used to run code before main(). Destructors of globals can be used to run code after main(). Dynamic initialization of globals in dynamically loaded objects can be used to run code on plugin load.

Cons: It is very hard to reason about the order of execution of such functions. Especially if dynamically initialized globals are present in shared libraries that are linked into dynamically loaded objects, few people understand the semantics.

As an example do this:

struct Pod 
{
  int indexes[5];
  float width;
};
struct LiteralType 
{
  int value;
  constexpr LiteralType() : value(1) {}
};

Pod gData;   
LiteralType gOtherData;

But not this :

class NotPod 
{
  NotPod();
};
NotPod gBadData;  // dynamic constructor

Decision: Global variables must be initialized statically.
We only allow global variables to contain POD data. This rule completely disallows std::vector (use std::array instead), or std::string (use const char []) for global variables.

Extra details and exceptions to the rules:

// Struct.h:
#include <string>
struct Struct 
{
  static std::string sString;
};

// Struct.cxx:
std::string Struct::sString = "Hello World";

// main.cxx:
#include "Struct.h"
#include <iostream>

std::string gAnotherString = Struct::sString;

int main() 
{
  std::cout << gAnotherString << std::endl;
  return 0;
}

Definition: Function-local static variables are initialized on first use and destructed in the reverse order of construction.

Pros: The variable is lazily initialized. Therefore the order of construction is better under control. Also the cost of initialization is only incurred if it is really needed.

Cons: Because of the thread-safe lazy initialization, function-local static variables have an extra cost compared to other function variables.

Decision: Use static class variables rather than function-local static variables. Therefore, do this :

class Something
{
 public:
  int generateId() {
    return Something::sId++;
  }

 private:
  static int sId; // initialized in .cxx
};

class Something
{
 public:
  int generateId() {
    static int sId = 0;
    return sId++;
  }
};

Extra details and exceptions to the rules:

std::string &globalMessage()
{
  static std::string message = "Hello world.";
  return message;
}

int main()
{
  std::cout << globalMessage() << '\n';
  globalMessage() = "Goodbye cruel world.";
  std::cout << globalMessage() << '\n';
  return 0;
}
// prints:
// Hello world.
// Goodbye cruel world.

class BreakTheCode
{
 public:
  void setReference(int *value) { mValuePointer = value; }
  ~BreakTheCode() { *mValuePointer += 2; }

 private:
  int *mValuePointer = 0;
};

BreakTheCode &globalBreaker()
{
  static BreakTheCode breaker;
  return breaker;
}

int main()
{
  int someValue = 1;
  globalBreaker().setReference(&someValue);
  return 0;
}
// globalBreaker::breaker accesses main::someValue after it went out of scope.
// This example should be harmless, but if a more complex type instead of int
// is involved — and possibly the destructor of another function-local
// static overwrites the stack data from main — this pattern can lead to a crash.

class MyClass 
{
 public:
  MyClass() = default;
  MyClass(int z) : a(z) {}

  int data() const {
    return a;
  }

 private:
  int a = 1234;  // in-class initialization
};

int main() 
{
  MyClass firstClass;
  MyClass secondClass{5678};

  std::cout << firstClass.data()
    << ' ' << secondClass.data();
  return 0;
}

Definition:

Class member variables are initialized in the order in which they are declared in the class definition. The order in the constructor initializer list has no influence on initialization order and therefore may be misleading if it does not match the order of the declaration. Compilers often issue a warning if this rule is broken, but not always.

If a member variable is not explicitly initialized in the constructor initializer list the default constructor of that variable is called. Therefore, if a member variable is assigned to in the constructor function body, the member variable may get initialized unnecessarily with the default constructor.

If you do not declare any constructors yourself then the compiler will generate a default constructor for you, which may leave some fields uninitialized or initialized to inappropriate values.

Examples:

In-class member initialization:

// MyClass.h
class MyClass 
{
 // ...
 private:
  int mValue = 1234;
};

Initialization list:

// MyClass.h
class MyClass : public MyBase  
{
 // ...
 private:
  int mValue;
  std::vector mVector;
};
// MyClass.cxx
MyClass::MyClass()
  : MyBase(),
    mValue(0),
    mVector()
{}

See an example of initialization via std::initializer_list in Brace Initialization.

Decision:

Member variables should be declared and initialized in the same order.

Use in-class member initialization for simple initializations, especially when a member variable must be initialized the same way in more than one constructor.

If your class defines member variables that aren't initialized in-class, and if it has no other constructors, you must define a default constructor (one that takes no arguments). It should preferably initialize the object in such a way that its internal state is consistent and valid.

If your class inherits from an existing class but you add no new member variables, you are not required to have a default constructor.

Avoid unmanaged resource acquisition in constructors, since the destructor of the class will not be called if an exception is thrown from the constructor. Therefore, always use C++ "resource acquisition is initialization" (RAII) idiom to ensure resources are properly freed.

Extra details and exceptions to the rules:

// MyClass.h
class MyClass 
{
 public:
  MyClass();
  ~MyClass();
 
 private:
  Something* mSomething;  // raw pointer
};
// MyClass.cxx
MyClass::MyClass()
  : mSomething(new Something()) 
{}     
MyClass::~MyClass()
{
  delete mSomething;       // mSomething has to be deleted with its owner
}     

// MyClass.h
class MyClass 
{
 public:
  MyClass();
  ~MyClass() = delete;   // mSomething is deleted automatically
 private:
  std::unique_ptr<Something> mSomething; // smart pointer
};
// MyClass.cxx
MyClass::MyClass()
  : mSomething(new Something())
{}     

Inside constructors and destructors virtual function do not behave "virtually". If the work calls virtual functions, these calls will not get dispatched to the subclass implementations. Calls to an unimplemented pure virtual function result in undefined behavior.

Calling a virtual function non-virtually is fine:

class MyClass 
{
 public:
  MyClass() { doSomething(); }    // Bad
  virtual void doSomething();
};

class MyClass 
{
 public:
  MyClass() { MyClass::doSomething(); }    // Good
  virtual void doSomething();
};

Decision: Constructors should never call virtual functions.

Definition: Normally, if a constructor takes one argument, it can be used as a conversion. For instance, if you define

class Foo 
{
 public:
  Foo(const std::string &name);
};

class MyClass 
{
 public:
  explicit MyClass(int number); //allocate number bytes 
  explicit MyClass(const std::string &name); // initialize with string name
 };

Decision:

We require all single argument constructors to be explicit.

Exceptions are copy constructors and classes that are intended to be transparent wrappers around other classes.

Finally, constructors that take only an initializer_list may be non-explicit. This is to permit construction of your type using the assignment form for brace init lists (i.e. MyType myObject = {1, 2} ).

Definition: The copy constructor and copy assignment operator are used to create copies of objects. The move constructor and move assignment operator are used to move (semantically) objects.

Decision:

Classes that use value semantics normally need to be copyable. If they are not copyable (e.g. unique resource ownership) they should be movable. If the copy constructor is trivial (which normally implies an empty destructor) it can be useful for performance reasons to use the key word default:

ClassName(const ClassName &other) = default;

ClassName(const ClassName &other)
  : data(other.data) {}

Polymorphic class design implies pointer semantics. These classes should have their copy constructors disabled via delete:

ClassName(const ClassName &) = delete;
ClassName &operator=(const ClassName &) = delete;

If your polymorphic class needs to be copyable, use a virtual clone() method. This way copying can be implemented without slicing and be used more naturally for pointers:

void someFunction(SomeInterface *object)
{
  SomeInterface *objectCopy = object->clone();
  ...
}

Definition:

Delegating and inheriting constructors are two different features, both introduced in C++11, for reducing code duplication in constructors. Delegating constructors allow the constructor to forward work to another constructor of the same class, using a special variant of the initialization list syntax. For example:

Foo::Foo(const string& name) : mName(name) 
{
  ...
}

Foo::Foo() : Foo("example") { }

A subclass, per default, inherits all functions of the base class. This is not the case for constructors. Since C++11 it is possible to explicitly inherit the constructors of a base class. This can be a significant simplification for subclasses that don't need custom constructor logic.

class Base 
{
 public:
  Base();
  explicit Base(int number);
  explicit Base(const string& name);
  ...
};

class Derived : public Base 
{
 public:
  using Base::Base;  // Base's constructors are redeclared here.
};

This is especially useful when Derived's constructors don't have to do anything more than calling Base's constructors.

Decision:

Use delegating and inheriting constructors when they reduce code duplication.
Be cautious about inheriting constructors when your derived class has new member variables and use in-class member initialization for the derived class's member variables.

The struct and class keywords behave almost identically in C++. We add our own semantic meanings to each keyword, so you should use the appropriate keyword for the data-type you're defining.

structs should be used for passive objects that carry data, and may have associated constants, but lack any functionality other than access/setting the data members. The accessing/setting of fields is done by directly accessing the fields rather than through method invocations. Methods should not provide behavior but should only be used to set up the data members, e.g., constructor, destructor, initialize(), reset(), validate().

If more functionality is required, a class is more appropriate.

You can use struct instead of class for functors and traits.

Note that member variables in structs and classes have different naming rules.

In polymorphic design a special care is needed in implementing base class destructors. If deletion through a pointer to a base Base should be allowed, then the Base destructor must be public and virtual. Otherwise, it should be protected and can be non-virtual.

Decision:

Always write a destructor for a base class, because the implicitly generated one is public and nonvirtual.

Extra details and exceptions to the rules:

Definition: When a sub-class inherits from a base class, it includes the definitions of all the data and operations that the parent base class defines. In practice, inheritance is used in two major ways in C++: implementation inheritance, in which actual code is inherited by the child, and interface inheritance, in which only method names are inherited.

Pros: Implementation inheritance reduces code size by re-using the base class code as it specializes an existing type. Because inheritance is a compile-time declaration, you and the compiler can understand the operation and detect errors. Interface inheritance can be used to programmatically enforce that a class expose a particular API. Again, the compiler can detect errors, in this case, when a class does not define a necessary method of the API.

Cons: For implementation inheritance, because the code implementing a sub-class is spread between the base and the sub-class, it can be more difficult to understand an implementation. The sub-class cannot override functions that are not virtual, so the sub-class cannot change implementation. The base class may also define some data members, so that specifies physical layout of the base class.

Decision:

All inheritance should be public. If you want to do private inheritance, you should be including an instance of the base class as a member instead.

Do not overuse implementation inheritance. Composition is often more appropriate. Try to restrict use of inheritance to the "is-a" case: Bar subclasses Foo if it can reasonably be said that Bar "is a kind of" Foo.

Definition: Multiple inheritance allows a sub-class to have more than one base class. However this functionality can bring to the so-called Diamond problem unless base classes are pure interfaces.

Decision: Multiple inheritance is allowed only when all superclasses, with the possible exception of the first one, are pure interfaces.

Definition:

A class is a pure interface if it meets the following requirements:

• It has only public pure virtual ("= 0") methods and static methods (see Destructors).
• It does not have data members.
• It does not have any constructors defined. If a constructor is provided, it must take no arguments and it must be protected.
• If it is a subclass, it may only be derived from classes that satisfy these conditions.

Decision: When writing a pure interface, apply the corresponding naming rule and make sure there is no implementation in it. Make sure not to add implementation to an existing pure interface.

Definition: Operator overloading is a specific case of function overloading in which some or all operators like +, = or == have different behaviors depending on the types of their arguments. It can easily be emulated using function calls.

For example: a << 1; shifts the bits of the variable left by one bit if a is an integer, but if a is an output stream instead this will write "1" to it.

Decision:

The semantics of the operator overloading should be kept the same. Because operator overloading allows the programmer to change the usual semantics of an operator, it should be used with care.

Information hiding protects the code from uncontrollable modifying state of your object by clients and it also help to minimize dependencies between calling and called codes.

A class consisting mostly of gets/sets is probably poorly designed. Consider providing an abstraction or changing it in struct.

Decision: Make data members private, except in structs. If there is no better way how to hide the class internals, provide the access through protected or public accessor and, if really needed, modifier functions.

See also Inheritance, Structs vs. Classes and Function Names.

Exceptions should be used only when it is guaranteed that they cannot affect the performance, otherwise use return values.
Use exceptions mainly for errors that shall terminate the application (std::bad_alloc, std::runtime_error("not implemented"), ...)
If exception handling is needed, don't use generic or standard types for that (int, std::bad_alloc), but create your own type which is only used by youself, to avoid conflicts.
Your class can typically derive from std::exception (or one of its subclasses like std::runtime_error).
Exceptions should be scoped inside the class that throws them.
Catch only your custom exceptions. In particular, try to avoid catchalls, but if they are absolutely necessary, rethrow afterwards, and add an option (e.g. environment variable) to disable the catchall.
For code inside O2 (or having O2 as dependency), consider using o2::framework::runtime_error, which provides automatic stacktraces and formatting.
By default, catch exceptions by reference.

int computePedestals()
{
  ...
  if (somethingWrong) {
    throw BadComputation();
  }
  ...
}
...
try {
  computePedestals();
} catch (BadComputation& e) {  // catch exception by reference
  // code that handles error
   ...
}

int computePedestals()
{
  ...
  if (somethingWrong) {
    return -1;  
  }
  ...         
}
...
if (computePedestals() == -1) {
  // code that handles error
  ...
}

Definition:

Decision:

const variables, data members, methods and arguments add a level of compile-time type checking; it is better to detect errors as soon as possible. Therefore we strongly recommend that you use const whenever it makes sense to do so.

Use const:

• for an argument, if the function does not modify it when passed by reference or by pointer.
• For accessors.
• For methods, if they:
  • do not modify any non-local data;
  • can be safely (no data race) called from multiple threads;
  • do not call any non-const methods;
  • do not return a non-const pointer or non-const reference to a data member.
• For data members, whenever they do not need to be modified after construction.

Extra details and exceptions to the rules:

Definition: Some variables can be declared constexpr to indicate the variables are true constants, i.e. fixed at compilation/link time. Some functions and constructors can be declared constexpr which enables them to be used in defining a constexpr variable.

Pros: Use of constexpr enables definition of constants with floating-point expressions rather than just literals; definition of constants of user-defined types; and definition of constants with function calls.

Cons: Prematurely marking something as constexpr may cause migration problems if later on it has to be downgraded. Current restrictions on what is allowed in constexpr functions and constructors may invite obscure workarounds in these definitions.

Decision:

constexpr definitions enable a more robust specification of the constant parts of an interface. Use constexpr to specify true constants and the functions that support their definitions. Avoid complexifying function definitions to enable their use with constexpr. Do not use constexpr to force inlining.

Extra details and exceptions to the rules:

constexpr int GlobalScopeValue = 0;

namespace namespace 
{
  constexpr int ScopeValue = 1;
}

struct Struct 
{
  static constexpr int ScopeValue = 1;
};

template<typename T> struct TemplateStruct 
{
  static constexpr int ScopeValue = 1;
};

void function(const int &value);

function(GlobalScopeValue);      // fine
function(Namespace::ScopeValue); // fine
function(Struct::ScopeValue);    // link error
function(TemplateStruct<int>::ScopeValue); // link error

template<typename T> constexpr int TemplateStruct<T>::ScopeValue;

constexpr int Struct::ScopeValue;

Definition:

Unique ownership ensures that there can be only one smart pointer to the object. If that smart pointer goes out of scope it will free the pointee.

Shared ownership allows to have multiple pointers to an object without deciding who is the exclusive owner. Thus the owners can be freed in any order and the pointer will stay valid until the last one is freed, in which case the pointee is also freed. Note that shared_ptr<T> is thread-safe and thus enables sharing ownership over multiple threads.

Example:

{
  std::shared_ptr<int> first;
  {
    std::unique_ptr<int> second(new int);
    auto third = std::make_shared<int>();
    first = third;
  }
  // only second is freed automatically here
}
// first and third are automatically freed here

A weak pointer (weak_ptr<T>) can be used to break cyclic ownership.

Pros: Smart pointers are extremely useful for preventing memory leaks, and are essential for writing exception-safe code. They also formalize and document the ownership of dynamically allocated memory.

Cons: Smart pointers enable sharing or transfer of ownership and can thus act as a tempting alternative to careful design of ownership semantics. This could lead to confusing code and even bugs in which memory is never deleted.

Decision:

std::unique_ptr

Straightforward and risk-free. This should be your default for any pointer.

std::shared_ptr

If you really need to share ownership, use a shared_ptr. You should avoid designs that require shared ownership, though, as it incurs an overhead. unique_ptr on the other hand is without overhead.

Extra details and exceptions to the rules:

void function(shared_ptr<int> value)
{
  *value = 0;
}

void otherFunction()
{
  auto ptr = make_shared<int>();
  function(ptr);
  ...
}

void function(int *value) // caller retains ownership
{
  *value = 0;
}

void otherFunction()
{
  unique_ptr<int> ptr{new int};
  function(ptr.get());
  ...
}

Avoid spelling literal constants like 42 or 3.141592 in code. Use symbolic names and expressions instead. Names add information and introduce a single point of maintenance.

Example of constants at namespace level:

static constexpr double Millimeter  = 1.;
static constexpr double Centimeter  = 10.*Millimeter;

Example of class-specific constants:

// File Widget.h
class Widget 
{
 private:
  static const int sDefaultWidth;           // value provided in definition
  static constexpr int DefaultHeight = 600; // value provided in declaration
};          

// File Widget.cxx
const int Widget::sDefaultWidth = 800; // value provided in definition
constexpr int Widget::DefaultHeight;   // definition required only if reference/pointer to 
                                       // DefaultHeight is needed

Macros mean that the code you see is not the same as the code the compiler sees. This can introduce unexpected behavior, especially since macros have global scope.

The following usage pattern will avoid many problems with macros; if you use macros, follow it whenever possible:

• Don't define macros in a .h file.
• Define macros (via #define) right before you use them, and undefine them (via #undef) right after.
• Do not just undefine an existing macro (via #undef) before replacing it with your own; instead, pick a name that's likely to be unique.
• Try not to use macros that expand to unbalanced C++ constructs, or at least document that behavior well.
• Prefer not using ## to generate function/class/variable names.
• Follow the naming convention as described here.

Long functions are hard to debug and makes readability difficult. Short functions allow code reuse. If a function exceeds about 40 lines, think about whether it can be broken up without harming the structure of the program.
Giving the function a name that describes what it does might help splitting it into smaller pieces. Functions should represent logical grouping, therefore it should be easy to assign them meaningful names.
Please note that nesting is not the same as splitting long functions into short ones. In addition, it does not improve readability and ease of debug.

Definition: RTTI allows a programmer to query the C++ class of an object at run time. This is done by use of typeid or dynamic_cast.

Cons:

Querying the type of an object at run-time frequently means a design problem. Needing to know the type of an object at runtime is often an indication that the design of your class hierarchy is flawed.

Undisciplined use of RTTI makes code hard to maintain. It can lead to type-based decision trees or switch statements scattered throughout the code, all of which must be examined when making further changes.

Decision trees based on type are a strong indication that your code is on the wrong track.

if (typeid(*data) == typeid(Data1)) {
  ...
} else if (typeid(*data) == typeid(Data2)) {
  ...
} else if (typeid(*data) == typeid(Data3)) {
...

Pros:

The standard alternatives to RTTI (described below) require modification or redesign of the class hierarchy in question. Sometimes such modifications are infeasible or undesirable, particularly in widely-used or mature code.

RTTI can be useful in some unit tests. For example, it is useful in tests of factory classes where the test has to verify that a newly created object has the expected dynamic type. It is also useful in managing the relationship between objects and their mocks.

// Example of a unit test
Geo::Factory geoFactory;
Geo::Object* circle = geoFactory.CreateCircle();
if ( ! dynamic_cast<Geo::Circle>(circle) ) {
  std::cerr << "Unit test failed."  << std::endl;
}  

Decision:

RTTI has legitimate uses but is prone to abuse, so you must be careful when using it. You may use it freely in unittests, but avoid it when possible in other code. In particular, think twice before using RTTI in new code. If you find yourself needing to write code that behaves differently based on the class of an object, consider one of the following alternatives to querying the type:

• Virtual methods are the preferred way of executing different code paths depending on a specific subclass type. This puts the work within the object itself.
• If the work belongs outside the object and instead in some processing code, consider a double-dispatch solution, such as the Visitor design pattern. This allows a facility outside the object itself to determine the type of class using the built-in type system.

When the logic of a program guarantees that a given instance of a base class is in fact an instance of a particular derived class, then use of a dynamic_cast or static_cast as an alternative may be also justified in such situations.

Extra details and exceptions to the rules:

void foo(Bar* bar) {
  // ... some code where x, y, z are defined ...
  // ...
  if (Data1 data1 = dynamic_cast<Data1*>(bar)) {
    doSomething(data1, x, y);
  }
  else if (Data2 data2 = dynamic_cast<Data2*>(bar)) {
    doSomething(data2, z)
  }

void foo(Bar* bar) 
{
  // ... some code where x, y, z are defined ...
  // ...
  DoSomethingVisitor visitor(x, y, z);
  bar.accept(visitor);
}

Decision:

• Try to avoid casts. The need for casts may be a hint that too much type information was lost somewhere.
• Use static_cast to explicitly convert values between different types. static_casts are useful for up-casting pointers in an inheritance hierarchy.
• Avoid const_cast. (Possibly use mutable member variables instead.) const_cast may be used to adapt to const-incorrect interfaces that you cannot (get) fix(ed).
• reinterpret_casts are powerful but dangerous. Rather try to avoid them. Code that requires a reinterpret_cast should document the aliasing implications. (reinterpret_cast on cppreference.com)

See the RTTI section for guidance on the use of dynamic_cast.

Extra details and exceptions to the rules:

std::uint32_t fun()
{
  std::uint32_t binary = 0;
  reinterpret_cast<float &>(binary) = 1.f;
  return binary; // the return value is undefined, according to the C++ standard
}

std::uint32_t fun()
{
  float value = 1.f;
  return reinterpret_cast<std::uint32_t &>(value); // this returns 0x3f800000 on x86
}

Pros: Stack-allocated objects avoid the overhead of heap allocation. Variable-length arrays and alloca allow variably-sized stack allocations, whereas all other stack allocations in C++ only allow fixed-size objects on the stack.

Cons: Variable-length arrays are part of C but not Standard C++. alloca is part of POSIX, but not part of Standard C++.

Decision: Use STL containers instead. If you really need to improve the performance consider using a custom allocator for the containers.

If not conditional on an enumerated value, switch statements should always have a default case (in the case of an enumerated value, the compiler will warn you if any values are not handled). If the default case should never execute, simply assert:

switch (value) {
  case 0: {  // 2 space indent
    ...      // 4 space indent
    break;
  }
  case 1: {
    ...
    break;
  }
  default: {
    assert(false);
  }
}

Empty loop bodies should use {} or continue, but not a single semicolon.

while (condition) {
  // Repeat test until it returns false.
}
for (int i = 0; i < someNumber; ++i) {}  // Good — empty body.
while (condition) continue;  // Good — continue indicates no logic.

while (condition);  // Bad — looks like part of do/while loop.

The C++ standard only loosely specifies the sizes of its built-in integer types.

If you need something other than int, consider one of the integer types in <cstdint>.

On Unsigned Integers

Using unsigned types to represent numbers that are never negative may be a source of problems as demonstrated here:

for (unsigned int i = foo.getLength() - 1; i >= 0; --i) ...

This code will never terminate! A compiler might notice the issue and warn you, but do not count on it. Equally bad bugs can occur when comparing signed and unsigned variables.

To avoid such situation we recommend to consistently use int:

for (int i = static_cast<int>(foo.getLength()) - 1; i >= 0; --i) ...

Below we give a list (incomplete) of possible portability issues:

• printf() specifiers for some types are not cleanly portable between 32-bit and 64-bit systems.
• Remember that sizeof(void *) != sizeof(int). Use intptr_t if you need a pointer-sized integer.
• You may need to be careful with structure alignments, particularly for structures being stored on disk.
• The data memory representation is computer specific and not defined by C++. The terms endian and endianness, refer to how bytes of a data word are ordered within memory. Big endian store bytes from the highest to the lowest, Little endian from the lowest to the highest.

nullptr is a pointer literal of type std::nullptr_t. On the other hand, NULL is a macro equivalent the integer 0. Using NULL could bring to unexpected problems. For example imagine you have the following two function declarations:

void function(int number);
void function(char *name);

function( NULL );

Use sizeof(varname) when you take the size of a particular variable. sizeof(varname) will update appropriately if someone changes the variable type either now or later. You may use sizeof(type) for code unrelated to any particular variable, such as code that manages an external or internal data format where a variable of an appropriate C++ type is not convenient.

Struct data;
memset(&data, 0, sizeof(data));

memset(&data, 0, sizeof(Struct));

if (rawSize < sizeof(int)) {
  logMessage << "compressed record not big enough for count: " << rawSize; 
}

Definition: In C++11, a variable whose type is given as auto will be given a type that matches that of the expression used to initialize it. You can use auto either to initialize a variable by copying, or to bind a reference.

vector<string> names;
...
auto name1 = names[0];  // Makes a copy of names[0].
const auto& name2 = names[0];  // name2 is a reference to names[0].

Pros:

C++ type names can sometimes be long and cumbersome, especially when they involve templates or namespaces. In a statement like

sparse_hash_map<string, int>::iterator iter = myMap.find(val);

auto iter = myMap.find(val);

Without auto we are sometimes forced to write a type name twice in the same expression, adding no value for the reader, as in

diagnostics::ErrorStatus* status = new diagnostics::ErrorStatus("xyz");

Using auto makes it easier to use intermediate variables when appropriate, by reducing the burden of writing their types explicitly.

auto status = new diagnostics::ErrorStatus("xyz");

Cons:

Sometimes code is clearer when types are manifest, especially when the initialization of a variable depends on functions/variables that were declared far away. In an expression like

auto i = xValue.Lookup(key);

Programmers have to understand the difference between auto and const auto& or they'll get copies when they didn't mean to.

The interaction between auto and C++11 brace-initialization can be confusing. The declarations

auto xValue(3);  // Note: parentheses.
auto yValue{3};  // Note: curly braces.

If an auto variable is used as part of an interface, e.g. as a constant in a header, then a programmer might change its type while only intending to change its value, leading to a more radical API change than intended.

Decision:

auto is permitted for local variables only. Do not use auto for file-scope or namespace-scope variables, or for class members. Never assign a braced initializer list to an auto-typed variable.

To modify code that was written to specifications other than those presented by this guide, it may be necessary to deviate from these rules in order to stay consistent with the local conventions in that code. In case of doubt the original author or the person currently responsible for the code should be consulted. Remember that consistency also includes local consistency.