ALICE O² C++ Naming & Formatting Rules

How to Name

Within reason, give as descriptive a name as possible. Do not worry about saving horizontal space as it is far more important to make your code immediately understandable to a new reader. Examples of well-chosen names:

int numberOfErrors;               // Good.
int numberOfCompletedConnections; // Good.

Poorly chosen names use ambiguous abbreviations or arbitrary characters that do not convey meaning. Do not use directly the variable names from mathematical formulas. In mathematics, variable names are usually limited to a single letter. To implement a mathematical formula use variable names that clearly indicate what value it holds.

float distance = velocity * time; // Good - no ambiguity

int n;           // Bad - meaningless.
int nerr;        // Bad - ambiguous abbreviation.
int nCompConns;  // Bad - ambiguous abbreviation.
float s = v * t; // Bad - almost meaningless.

Type and variable names should typically be nouns: e.g., FileOpener, numberOfErrors.

Function names should typically be imperative (that is they should be commands): e.g., openFile(), setNumberOfErrors().

CamelCase Convention

All names in C++ code follow camel case convention. This is the practice of writing compound words so that each word begins with a capital letter. No underscores are allowed. Acronyms are the only exception : they can be capitalized.

For example:

string tableName;   // Good

class ITSReco       // Good, acronyms can be capitalized

string table_name;  // Bad - uses underscore.
string tablename;   // Bad - all lowercase.

Capitalization Rules

Variables and functions start with a lowercase letter.
Everything else in C++ code (type names, constant expressions) starts with an uppercase letter.

Abbreviations

Do not use abbreviations except for acronyms. For example:

// Good. These show proper names with no abbreviations.
int numberOfDnsConnections;   // Most people know what "DNS" stands for.
int priceCount;               // Price count, it makes sense.
int daqRate;                  // In ALICE everyone knows what DAQ stands for.

// Bad. Abbreviations can be confusing or ambiguous outside a small group.
int wgcConnections;  // Only your group knows what this stands for.
int pcReader;        // Lots of things can be abbreviated "pc".

A single letter variable name can be used for well-known idioms like iterators of integer type and pimpl-idioms (d-pointer).

for (int i = 0 ; i < 10 ; i++) { // Good.
  prices[i] = 0;
}

for (auto i = &prices[0]; i < &prices[10]; ++i) { // Bad
  *i = 0;                        // i is not of integer type
}

Never abbreviate by leaving out letters.
Exception: You may use it for iterator names or their names prefix.

// Good
std::vector<int > myVector;
auto it = myVector.begin();               
auto itMyVector = myVector.begin();       
auto myVectorIterator = myVector.begin(); 

auto myVectorIt = myVector.begin();       // Bad. It is abbreviated, but not a prefix.

C++ implementation files should end in .cxx and header files should end in .h.

Inline functions should go directly into your .h file. However, if they include a lot of code, they may go into a third file that ends in .inl. This rule applies to templates too.

Do not use filenames that already exist in /usr/include, such as db.h.

Examples of acceptable file names:

MyClass.h       // The class declaration.
MyClass.cxx     // The class definition.
MyClass.inl     // Inline functions that include lots of code.
myUtilities.h   // Utility functions/definitions
testMyClass.cxx // Test program

Having upper case letters in a file name might theoretically lead to problems for case-insensitive operating systems. However, as the file name corresponds to the class name it seems important to keep the same case as well. Moreover, having two valid class/file names that would collide on a not-case sensitive OS seems extremely unlikely.

When applicable, the o2 prefix is immediately followed by the subsystem short name.

For example:

  o2-sim
  o2-conditions-client
  o2-digitizer-workflow
  o2-tpc-reco-workflow
  o2-tpc-monitor
  o2-flp-sender-device
        

When applicable, the O2 prefix is immediately followed by the subsystem short name (in upper case).

For example:

libO2CPVSimulation.dylib
libO2HitAnalysis.dylib
libO2TPCMonitor.dylib
      

The names of all types — classes, structs, typedefs, and enums — have the same naming convention. For example:

// classes and structs
class UrlTable 
{ ...
class UrlTableTester 
{ ...
struct UrlTableProperties 
{ ...

// typedefs
typedef HashMap<UrlTableProperties *, string> PropertiesMap;

// enums
enum UrlTableErrors { ...

Local Variable names

For example:

string tableName;   // Good.

Class Data Members

Data members (also called instance variables or member variables) are prefixed with m. If the data member is static, prefix the variable with s instead.

class Something 
{
 private:
  string mTableName;      
  static int sGlobalState;
};

Struct Variables

Data members in structs are named like regular variables.

struct UrlTableProperties 
{
  string name;
  int numberOfEntries;
}

Global Variables

Global variables, which should be rare in any case, are prefixed with g.

constexpr

A variable declared as constexpr typically is only used as compile-time constant (but may be stored in read-only memory). Therefore it uses the same convention as enums and uses uppercase CamelCase.

constexpr double LightSpeed = 2.99792458e+8;

const

A variable declared as const does not have any additional naming rules. The prefixes describe the scope of the variable. const is just one aspect of the type of the variable.

To provide a constant in the public interface consider constexpr, enum, or a (constexpr) function instead.

Regular Functions

Example of functions:

addTableEntry();
deleteUrl();

The rule applies also to constexpr functions:

constexpr int getFive() { return 5; }       

Accessors and Mutators

Accessors and mutators match the name of the variable they are getting and setting and use the prefixes get and set. The prefixes get and set are not exclusive for accessors and mutators and they could be used for other functions, if applicable. This shows an excerpt of a class whose instance variable is mNumberOfEntries:

class MyClass 
{
 public:
 ...
  int getNumberOfEntries() const { return mNumberOfEntries; }
  void setNumberOfEntries(int numberOfEntries) { mNumberOfEntries = numEntries; }
 private:
  int mNumberOfEntries;
};

Functions returning a boolean value

Functions returning a boolean value should be prefixed with is or has:

bool isOpen();
bool hasZero();

This rule applies also to class member functions where is or has replace get:

class MyClass 
{
 public:
  void setValid(bool isValid) const { mValid = isValid; }
  bool isValid() const { return mValid; }
 private:
  bool mValid;
};

Definition: A scoped enum is one that is declared with the class keyword, as opposed to a traditional enum, which is unscoped and doesn't include the class keyword in its declaration.

Unscoped enumerators are exposed to the enclosing scope. Therefore they should be prefixed or postfixed (decided by which position makes the code more prose-like) with the enumeration's name (or a sensible part thereof). All names use uppercase CamelCase.

Example of an unscoped enumeration:

enum Something {
  SomethingSmall,   // the type name as prefix
  SomethingBig,
  SomethingElse
};

void add(Something);
...
add(SomethingSmall);
add(SomethingElse);

Another example of an unscoped enumeration whose enumerators are prefixed with just a (sensible) part of the type name.

enum MallocAlignment {
  AlignOnVector,    // the "Align" prefix taken from the type name
  AlignOnCacheline, 
  AlignOnPage
}

template<MallocAlignment A> void* malloc(size_t);
...
void* memory = malloc<AlignOnCacheline>(64);

Enum classes (new in C++11) create scoped enumerators. Therefore there is no need for prefixing or postfixing.

enum class Something : int {
  Small,
  Big,
  Unknown
};

void add(Something);
...
add(Something::Small);
add(Something::Unknown);

enum UrlTableErrors {
  Ok,                 // Bad.
  OutOfMemory         // Bad.
};

For the rules on Macro usage see here.

They must be named with all uppercase letters and underscores, prefixed with the sub/project name.

#define O2_VERTEX_ROUND(x) ...
#define O2_CORE_PI_ROUNDED 3.0

#define _WRONG
#define WRONG__AGAIN

Try keeping lines below 120 characters. In some cases it may make sense to use much longer lines (e.g. for block editing). But this should be confined to special sections in the code.

Spaces are used for indentation. Do not use tabs in your code. You should set your editor to emit spaces when you hit the tab key.

The return type, function name and open parenthesis are always on the same line. The open curly brace is at the beginning of the new line after the last parameter except for inline functions.

Example:

ReturnType ClassName::functionName(Type parName1, Type parName2) 
{
  doSomething();
  ...
}

Example of an inline function on one line:

inline int getValue() const { return mValue; }

The following are examples of correctly formatted pointer and reference expressions:

int value = *valuePointer;
int* valuePointer = &value;
int value = myObject->getValue();
int value = myStruct.value;

When declaring a pointer or reference, the `*` or `&` goes with the type.

// Pointers      
char* myCharacter;  // typical C++ notation
// References
const string& myString;

char * myCharacter;       // Bad - spaces on both sides of *
char *myCharacter;  // Bad - space before the *, the * is with the variable name.
const string &myString;   // Bad - the & is with the variable name.
const string & myString;  // Bad - spaces on both sides of &

In this example, the logical AND operator is always at the end of the lines:

if (thisOneThing > thisOtherThing &&
    aThirdThing == aFourthThing &&
    yetAnother && lastOne) {
  ...
}

Example of single-argument assignments:

int x = 3;                           // preferred style
std::string name = "Some Name"; 

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

Using {} for initialization is more consistent, more correct, and avoids having to know about old-style pitfalls [1].

Example of variable initialization:

Rectangle window{ 0, 0, 1024, 768 };    // preferred style
Rectangle window = { 0, 0, 1024, 768 }; // also possible
Rectangle window(0, 0, 1024, 768);      // avoid unless necessary

There is one exception: In rare cases a class may provide an std::initializer_list constructor and other constructors that are hidden by the std::initializer_list constructor. The hidden constructor can then still be accessed with ().

std::vector<int> v( 10, 20 ); // calls vector(size_t n, const int &value)
std::vector<int> v{ 10, 20 }; // calls vector(std::initializer_list<int> values)

Even when preprocessor directives are within the body of indented code, the directives should start at the beginning of the line.

// Good - directives at beginning of line
  if (lopsidedScore) {
#if DISASTER_PENDING      
    dropEverything();
# if NOTIFY               // Good but not required -- Spaces after #
    notifyClient();
# endif
#endif
    goBackToNormal();
  }

// Bad - indented directives
  if (lopsidedScore) {
    #if DISASTER_PENDING  // The "#if" should be at beginning of line
    dropEverything();
    #endif                // Do not indent "#endif"
    goBackToNormal();
  }

The basic format for a class declaration is:

class MyClass : public BaseClass 
{
 public:         // 1 spaces indent.
  MyClass();    // 2 spaces indent.
  ~MyClass() {}

  void someFunction();
  void someFunctionThatDoesNothing() {}
  void setSomeValue(int value) { mSomeValue = value; }

 private:
  bool someInternalFunction(); // notice that the method is before the data members

  int mSomeValue;
  int mSomeOtherValue;
};

Things to note:

• The base class name should be on the same line as the subclass name, subject to the 120-character limit.
• Except for the first instance, the access specifier keywords should be preceded by a blank line. This rule is optional for small classes.
• Do not leave a blank line after access specifier keywords.
• The public section should be first, followed by the protected and finally the private section.
• Generally, each access specifier appears only once in a class declaration.
• Within each section, the declarations should be in the following order:
  • Constructors
  • Destructor
  • Methods
  • Data Members

class A 
{
 private:             // Early declaration of a private data member
  int x;

 public:     
  decltype(x) foo(); // Needs x to be already declared
	     
 private:             // the rest of the private section
  float y;
};

The preferred format for initializer lists is:

MyClass::MyClass(int var)
  : mSomeVar(var),             // 2 space indent
    mSomeOtherVar(var + 1)     // lined up
{
  ...
  doSomething();
  ...
}

Another accepted format is:

// When it all fits on one line:
MyClass::MyClass(int var) : mSomeVar(var), mSomeOtherVar(var + 1) {}

Namespaces do not add an extra level of indentation. For example, use:

namespace 
{

void doSomething()  // Good.  No extra indentation within namespace.
{
  ...
}

} // namespace

Do not indent within a namespace:

namespace 
{

  void doSomething() // Bad.  Indented when it should not be 
  {
    ...
  }

}

When declaring nested namespaces, put each namespace on its own line.

namespace foo 
{
namespace bar 
{
...
}
}

The left curly brace is on the same line as the start of the statement.

if (condition) { // Correct. Curly brace on the same line.
} else {
}

if (condition)   // Bad. Curly brace on new line.
{
} 
else 
{
}

Exception: Class, struct and namespace declarations always have the opening brace on the start of a line. This applies also to functions, unless they are inlined.

class Debug
{
};

In control constructs (if statements, for loops etc.), use curly braces even when the body of the statement fits on one line:

// Good. Curly braces even for one statement body.
if (condition) {
  return true;
}

for (int i = 0; i < 10; ++i) {
  doSomething(i);
}

// Bad. No curly braces.
if (true)                         
  return true;

for (int i = 0; i < 10; ++i)
  doSomething(i);

Technically there is no right or wrong for whitespace as C++ does not really care about whitespaces. But on the other hand whitespaces can make a significant difference in whether code feels foreign or easy to understand to a developer. Thus, it is important that all developers become accustomed to the same style. This makes the communication via code much easier and enjoyable for everybody involved. Using one common whitespace style throughout a project also reduces unnecessary whitespace changes and thus makes diffs easier to read.

Example:

 int someFunction(int parameter) // No extra spaces inside parenthesis.
 {
   bool test = parameter > 4;    // Use spaces around binary operators.
   double value = -otherValue;   // No space between a unary operator and its operand.

   if (!test) {                  // Use one space after each keyword.
     return 1;
   }

   std::vector<std::vector<int>> someMatrix; 
                                 // No extra spaces between angle brackets (templates).

   std::string hello = "Hello World.";
   std::transform(hello.begin(), hello.end(), hello.begin(), [](char c) {
     return c + 1;
   });                           // This is the common style to embed lambdas (since C++11) 
                                 // in function calls.
   return 0;
 }

Sometimes there are good reasons to deviate from the rules to make the code structure more visible or align similar code in different lines. Feel free to insert/remove whitespace if it increases the readability / clarity of the code.

Do

const int* foo;

int const *foo;

Putting the const first is arguably more readable, since it follows English in putting the "adjective" (const) before the "noun" (int).

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.

For example, importing a full class from somewhere else , e.g. AliRoot, it is allowed to keep the naming scheme and the style as is. To use the "correct" naming and formatting scheme (described in this document), then to be consistent, the whole coding standard must be applied to the whole class.
Note: in the case that the whole formatting is changed then there should be one commit for the style changes and one for the actual code changes.