Style Guide

When working in a group environment, it is important to have a consistent style. Here are some general guide lines. Since the style has evolved over time, there are violations in the current code base. We will try to make things more consistent over time. This guide is a work is heavily inspired by Google's C++ style guide, but there are areas where this will of course differ.

NOTE: Because this is a work in progress, it is not being executed in the code base consistently yet.

Header Files

• Self-contained Headers

  Header files should be self-contained and end in .h. Files that are meant for textual inclusion, but are not headers, should end in .inc.

  All header files should be self-contained. In other words, users and refactoring tools should not have to adhere to special conditions in order to include the header. Specifically, a header should have header guards, should include all other headers it needs, and should not require any particular symbols to be defined.

  There are rare cases where a file is not meant to be self-contained, but instead is meant to be textually included at a specific point in the code. Examples are files that need to be included multiple times or platform-specific extensions that essentially are part of other headers. Such files should use the file extension .inc.

  If a template or inline function is declared in a .h file, define it in that same file. The definitions of these constructs must be included into every .cpp file that uses them, or the program may fail to link in some build configurations.

  As an exception, a function template that is explicitly instantiated for all relevant sets of template arguments, or that is a private member of a class, may be defined in the only .cpp file that instantiates the template.

• The #define Guard

  All header files should have #define guards to prevent multiple inclusion. The format of the symbol name should be <FILE>_H_ or <FILE>_<YYYY><MM><DD>_H_.

  For example, the file "Foo.h" might have the following guard:

  #ifndef FOO_20151016_H_
  #define FOO_20151016_H_
  
  #endif

• Inline Functions

  Define functions inline only when they are small, say, 10 lines or less.

• Forward Declarations

• Names and Order of Includes

Scoping

• Namespaces
• Nonmember, Static Member, and Global Functions
• Local Variables
• Static and Global Variables

Classes

• Doing Work in Constructors
• Implicit Conversions
• Copyable and Movable Types
• Delegating and Inheriting Constructors
• Structs vs. Classes
• Inheritance
• Multiple Inheritance
• Interfaces
• Operator Overloading
• Access Control
• Declaration Order

Functions

• Parameter Ordering
• Write Short Functions
• Reference Arguments
• Function Overloading
• Default Arguments
• Trailing Return Type Syntax

Other C++ Features

• Rvalue References
• Variable-Length Arrays and alloca()
• Friends
• Exceptions
• Run-Time Type Information (RTTI)
• Casting
• Streams
• Preincrement and Predecrement
• Use of const
• Use of constexpr
• Integer Types
• 64-bit Portability
• Preprocessor Macros
• 0 and nullptr/NULL
• sizeof
• auto
• Braced Initializer List
• Lambda expressions
• Template metaprogramming
• Boost
• std::hash
• C++11

Naming

• General Naming Rules
• File Names
• Type Names
• Variable Names
• Constant Names
• Function Names
• Namespace Names
• Enumerator Names
• Macro Names
• Exceptions to Naming Rules

Comments

• Comment Style
• File Comments
• Class Comments
• Function Comments
• Variable Comments
• Implementation Comments
• Punctuation, Spelling and Grammar
• TODO Comments
• Deprecation Comments

Formatting

• Line Length
• Non-ASCII Characters
• Spaces vs. Tabs
• Function Declarations and Definitions
• Lambda Expressions
• Function Calls
• Braced Initializer List Format
• Conditionals
• Loops and Switch Statements
• Pointer and Reference Expressions
• Boolean Expressions
• Return Values
• Variable and Array Initialization
• Preprocessor Directives
• Class Format
• Constructor Initializer Lists
• Namespace Formatting
• Horizontal Whitespace
• Vertical Whitespace