ALICE O² C++ Naming & Formatting Rules

Vasco Barroso
Alina GrigoraȘ
Ivana Hřivnáčová
Matthias Kretz
Adriana Telesca
Barthélémy von Haller

This document is based on the work of
B. Weinberger, C. Silverstein,
G. Eitzmann, M. Mentovai
and T.Landray
at http://google-styleguide.googlecode.com,
C++ Google Style guide, Revision 3.245
under the CC-By 3.0 License

Each style point has a summary for which additional information is available by toggling the accompanying arrow button that looks this way: . You may toggle all summaries with the big arrow button:

Toggle all summaries
Table of Contents

Background

The goal of this guide is to provide a number of rules that keep the code base manageable by enforcing consistency. It is very important that any programmer can look at another programmer's code and understand it quickly. Maintaining a uniform style and following conventions means that "pattern-matching" can be more easily used to identify different symbols and invariants.

Creating common, required idioms and patterns makes code much easier to understand. In some cases there might be good arguments for changing certain style rules. Nonetheless, for reasons of consistency the rules are left unchanged.

Note that this guide is not a C++ tutorial: we assume that the reader is familiar with the language.

Naming

The most important consistency rules are those that govern naming. The style of a name immediately informs us what sort of thing the named entity is: a type, a variable, a function, a macro, etc., without requiring us to search for the declaration of that entity. The pattern-matching engine in our brains relies a great deal on these naming rules.

Naming rules are pretty arbitrary, but we feel that consistency is more important than individual preferences in this area, so regardless of whether you find them sensible or not, the rules are the rules.

General Naming Rules

link
Names should be meaningful; abbreviations should be avoided. They follow camel case convention. Types and variables should be nouns, while functions should be "command" verbs.

Code File Names

link

C++ code file names are derived from the class (or the namespace) names.
Program file names and utility file names, which do not define a class or a namespace, start with a lower case letter.

Executable Names

link
Executable names should be in lowercase, prefixed with o2, and hyphenated : o2-tpc-reco-workflow

Library Names

link
Library names should follow camel case convention (with the exception of the subsystem names) and be prefixed with O2.

Type Names

link
Type names follow camel case convention and start with an upper case letter: MyClass, MyEnum.

Interface Names

link
The "Interface" suffix can optionally be used only if a class matches the Pure Interface requirements.

Variable Names

link
Variable names follow camel case convention and start with a lower case letter: myLocalVariable.
  • Class member variables are prefixed with m.
  • Static class member variables are prefixed with s.
  • No m prefix for struct members.
  • Global variables are prefixed with g.
  • constexpr variables are capitalized.
  • No additional prefix for const.

Function Names

link
Regular functions follow camel case convention and start with a lower case letter: myFunction().
  • Accessors and mutators match the name of the variable and are prefixed with get and set: getMyMemberVariable(), setMyMemberVariable().
  • Functions (including accessors) returning a boolean value should be prefixed with is or has.

Namespace Names

link
Namespace names follow underscore convention and start with a lower case letter: my_namespace.

Enumerator Names

link
Enumerations and enumerators (the type and the values) follow camel case convention and start with an upper case letter: MyEnumType, MyEnumValue.
  • Enumerators in unscoped enumerations should have a common prefix/postfix derived from the enumerations name.
  • Enum classes are already scoped and therefore the enumerators do not need a prefix/postfix.

Macro Names

link
All uppercase letters and underscores, prefixed with the sub/project name, i.e. MY_PROJECT_PKG1_MY_MACRO.

Formatting

Coding style and formatting are pretty arbitrary. However, a good project is much easier to follow if everyone uses the same style. Individuals may not agree with every aspect of the formatting rules, and some of the rules may be hard to get used to. Even so, it is important that all project contributors follow the style rules so that they can all read and understand everyone's code easily.

Line Length

link
Each line of text in your code should be at most 120 characters long.

One Statement Per Line

link
Prefer one statement per line because it improves code readability.

Spaces vs. Tabs

link
Indent with 2 spaces. Use only spaces, no tabs.

Function Declarations and Definitions

link
A function declaration is on one line if possible. Otherwise the parameters that do not fit are on the next line(s).

Pointer and Reference Expressions

link
No spaces around period or arrow. Pointer operators are either followed or preceded with a space.

Boolean Expressions

link
In the case of a boolean expression that is longer than the standard line length, lines should be broken up in a consistent way. All operators should be either at the beginning or at the end of the line.

Variable and Array Initialization

link
Prefer initialization with braces except for single-argument assignment.

Preprocessor Directives

link
The hash mark that starts a preprocessor directive is always at the beginning of the line.

Classes

link
Access specifiers in a class or a struct are indented by 1 space. The sections they delimit are themselves indented by 1 more space for a total of 2 spaces.

Constructor Initializer Lists

link
Constructor initializer lists should be with subsequent lines indented properly. Alternatively, they can be all in a single line.

Namespaces

link
The contents of namespaces are not indented.

Braces

link
As a base rule, the left curly brace is on the same line as the start of the statement. In control constructs, the braces must be used even if their body consists of only one statement.

Horizontal Whitespace

link
Recommended guidelines:
  • One space should be used after each keyword.
  • No extra spaces inside parenthesis and angle brackets (templates).
  • Spaces should be used around binary operators.
  • No space between a unary operator and its operand.
  • Never put trailing whitespace at the end of a line.

Vertical Whitespace

link
Use only one empty line to separate code.

Where to put const

link
Put const before the type when defining a const variable.

Exceptions to the Rules

The coding conventions described above have to be followed. However, like all good rules, these sometimes have exceptions.

Existing Non-conformant Code

link
It is permissible to deviate from the rules when dealing with code that does not conform to this style guide. For example, in naming something that is analogous to an existing C or C++ entity then the existing naming convention scheme can be followed.

Parting Words

Use common sense and BE CONSISTENT.

When editing code, take a few minutes to look at the code and determine its style.

The point about having style guidelines is to have a common vocabulary of coding so people can concentrate on what the programmer is saying, rather than on how he/she is saying it. Global style rules are presented here so people know the vocabulary. However, local style is also important. If the code added to a file looks drastically different from the existing code around it, the discontinuity throws readers out of their rhythm when they go to read it. Try to avoid this.

OK, enough writing about writing code; the code itself is much more interesting. Have fun!

References

[1] Herb Sutter on software, hardware, and concurrency blog [http://herbsutter.com/2013/05/09/gotw-1-solution]