C++ Style and Conventions

Resources

"The Elements of C++ Style" by Misfeldt, Bumgardner, and Gray has advice on formatting as well as many coding tips. Consult "C++ Coding Standards" by Sutter and Alexandrescu and "Effective C++" by Meyers for coding best practices. "Large Scale C++ Software Design" by Lakos is a very useful guide, (though a few sections are now a little dated).

Read the Style Guide for Python Code for a concise set of recommendations.

File Structure

Header Files

Header files have a .h or .hh suffix and the following structure. The first line tells emacs to use C++ mode. Next comes documentation of the file in Doxygen format. Include header files in the order: local, third-party, and then standard library files. The inclusion of Bar.ipp is only done if there is an inline definition file.

// -*- C++ -*-

/*! 
  \file foo/Bar.h
  \brief Concise explanation of what is implemented in this file.
*/

#if !defined(__foo_Bar_h__)
#define __foo_Bar_h__

// Local includes.
// Third-party includes.
// Standard library includes.

namespace foo {

// Class definitions and function declarations.

} // namespace foo

#define __foo_Bar_ipp__
#include "Bar.ipp"
#undef __foo_Bar_ipp__

#endif

Inline Definition Files

Inline definition files have the .ipp suffix. They have an include guard because their definitions should only be accessed through the associated header file.

// -*- C++ -*-

#if !defined(__foo_Bar_ipp__)
#error This file is an implementation detail of the class Bar.
#endif

namespace foo {

// Inline function definitions.

} // namespace foo

Compilation Units

Compilation units have a .cc suffix and the following structure.

// -*- C++ -*-

#include "Bar.h"
// Other includes.

namespace foo {

// Function definitions.

} // namespace foo

Formatting

Artistic Style

The code is automatically formatted with Artistic Style. To install astyle on your computer download the appropriate package and unpack it.

gunzip astyle.tar.gz
tar xvf astyle.tar

cd astyle/buildmac
make

cd ../bin
sudo mv astyle /usr/local/bin

To avoid frustration you will want to configure you source code editor to use the same conventions. If you use some version of emacs, place the following definitions in your configuration file. (For Aquamacs users this file is ~/Library/Preferences/Aquamacs Emacs/Preferences.el. Otherwise it is ~/.emacs.)

(setq c-basic-offset 4) ; Use four spaces for indentation.
(setq c-offsets-alist 
      '((member-init-intro . ++) ; Extra indentation for initializer lists.
	(innamespace . 0))) ; No indentation for namespaces.

Indentation

Use four spaces to indent blocks of code. For vi use the following command to set this convention.

:set cindent shiftwidth=4

Don't use indentation following namespace declarations. Otherwise almost all of your code will be indented.

namespace foo {
class Bar {
    ...
};
}

Use two indentation levels for initializers lists in constructors. This sets the initialization list apart from the function body.

class Foo {
    Foo(const std::size_t size) :
            _size(size),
            _data() {
        allocateMemory();
    }
};

Brace Placement

Place the opening brace on the line that controls entry into a block. The closing brace is on its own line following the end of the block.

void foo() {
  if (...) {
    ...
  }
  else {
    ...
  }
  while (...) {
    ...
  }
}

White Space

Use a space in the following places.

• Put a space after if, for, while, and do. This makes it look different that a function call.
• Put a space before and after binary operators such as =, ==, +, -, *, and /.

Naming Conventions

• Use uppercase and underscores for macros.
• Use upper camel for classes, structures, constants, enumerations, and types.
• Use lower camel for namespaces, functions, and variables.
• Use an underscore prefix for private member variables. Don't use an underscore for public member variables.
• Use a leading underscore for template parameters to avoid name clashes.

#define DEBUG_GEOM

const std::size_t SpaceDimension = 3;

class BoundingBoxTree {
public:
    typedef std::tr1::array<double, SpaceDimension> Point;
    enum {MaxLevel = 10};
private:
    std::vector<Point> _centers;
   ...
}

template<typename _T, std::size_t _Dimension>
bool makeBoundingBox(const std::vector<std::tr1::array<_T, _Dimension> > coordinates) {
    ...
}

std::endl vs. \n