C++ Best Practices

This document is meant to be a collaborative discussion of the best practices in C++. It compliments books such as Effective C++ (Meyers) and C++ Coding Standards (Alexandrescu, Sutter). We fill in some of the lower level details that they don't discuss and provide specific stylistic recommendations while also discussing how to ensure overall code quality.

In all cases brevity and succinctness is prefered. Examples are prefered for making the case for why one option is prefered over another. If necessary, words will be used.

Source control is an absolute necessity for any software development project. If you are not using one yet, start using one.

• github - allows for unlimited public repositories, must pay for a private repository
• bitbucket - allows for unlimited private repositories with up to 5 collaborators, for free.
• sourceforge - open source hosting only

Use an industry standard widely accepted build tool. This prevents you from reinventing the wheel whenever you discover / link to a new library / package your product / etc. Examples include:

• cmake
• waf
• ninja - can greatly improve the incremental build time of your larger projects. Can be used as a target for cmake
• google's build tool

Remember, it's not just a build tool, it's also a programming language. Try to maintain good clean build scripts and follow the recommended practices for the tool you are using

Once you have picked your build tool, set up a continuous integration environment.

Continuous Integration (CI) tools automatically build the source code as changes are pushed to the repository. These can be hosted privately or with a CI host.

• Travis CI
  • works well with C++
  • designed for use with github
  • free for public repositories on github
• Hudson CI
• Decent CI

If you have an opensource, publicly hosted project on github, go enable travis-ci integration right now. We'll wait for you to come back.

Use every available and reasonable set of warning options

You should use as many compilers as you can for your platform(s). Each compiler implements the standard slightly differently and supporting multiple will help ensure the most portable, most reliable code.

-Wall -Wextra -Wshadow -Wnon-virtual-dtor -pedantic

• -Wall -Wextra reasonable and standard
• -Wshadow warn the user if a variable declartion shadows one from a parent context
• -Wnon-virtual-dtor warn the user if a class with virtual functions has a non-virtual destructor. This helps catch hard to track down memory errors
• -pedantic

-Weffc++ warning mode can be too noisy, but if it works for your project, use it also.

/W4 - All reasonable warnings /w44640 - Enable warning on thread un-safe static member initialization

Not recommended

/Wall - Also warns on files included from the standard library, so it's not very useful and creates too many extra warnings.

Start with very strict warnings settings from the beginning. Trying to raise the warning level after the project is underway can be painful.

Consider using the "treat warnings as errors" setting. /Wx with MSVC, -Werror with GCC / Clang

ADD LINKS TO CHAISCRIPT's CHANGES FOR EACH OF THESE

include-what-you-use

clang-modernize

clang-check clang-tidy

Cppcheck is free and opensource. It strives for 0 false positives and does a good job at it. Therefor all warning should be enabled: -enable=all

Clang's analyzer's default options are good for the respective platform. It can be used directly from cmake. They can also be called via clang-check and clang-tidy from the LLVM Based Tools.

Can be enabled with the /analyze command line option. For now we will stick with the default options.

commercial options

A coverage analysis tool shall be run when tests are executed to make sure the entire application is being tested. Unfortunately, coverage analysis requires that compiler optimizations be disabled. This can result in significantly longer test execution times.

The most likely candidate for a coverage visualization is the lcov project. A secondary option is coveralls, which is free for open source projects.

• address
• thread
• undefined

If it is determined by team consensus that the compiler or analyzer is warning on something that is either incorrect or unavoidable, the team will disable the specific error to as localized part of the code as possible.

There should be a test enabled for every feature or bug fix that is committed. See also "Code Coverage Analysis."

Consistency of style is more important. Second most importance is following a style that the average C++ programmer is used to reading. C++ allows for arbitrary length identifier names, so there's no reason to be terse when naming variables. Use descriptive names, and be consistent in the style

• CamelCase
• snake_case

are common examples. snake_case has the advantage that it can also work with spell checkers, if desired.

• Types start with capitals: MyClass
• functions and variables start with lower case: myMethod
• constants are all capital: const int PI=3.14159265358979323;

Note that the C++ standard does not follow any of these guidelines. Everything in the standard is lowercase only.

Name private data with a m_ prefix to distinguish it from public data.

Name function parameters with an t_ prefix.

http://stackoverflow.com/questions/228783/what-are-the-rules-about-using-an-underscore-in-a-c-identifier

If you do, you risk broaching on names reserved for implementation use

http://stackoverflow.com/questions/228783/what-are-the-rules-about-using-an-underscore-in-a-c-identifier

class MyClass
{
public:
  MyClass(int t_data)
    : m_data(t_data)
  {
  }
  
  int getData() const
  {
    return m_data;
  }
  
private:
  int m_data;
};

Not the source folder

C++11 introduces nullptr which is a special type denoting a null pointer value. This should be used instead of 0 or NULL to indicate a null pointer.

Comment blocks should use //, not /* */. Using // makes it much easier to comment out a block of code while debugging.

// this function does something
int myFunc()
{
}

To comment out this function block during debugging we might do:

/*
// this function does something
int myFunc()
{
}
*/

which would be impossible if the function comment header used /* */

This causes the name space you are using to be pulled into the namespace of the header file.

Header files must contain an distinctly named include guard to avoid problems with including the same header multiple times or conflicting with other headers from other projects

#ifndef MYPROJECT_MYCLASS_HPP
#define MYPROEJCT_MYCLASS_HPP

namespace MyProject {
class MyClass {
};
}

#endif

Leaving them off can lead to semantic errors in the code.

// Bad Idea
// this compiles and does what you want, but can lead to confusing
// errors if close attention is not paid.
for (int i = 0; i < 15; ++i)
  std::cout << i << std::endl;

// Bad Idea
// the cout is not part of the loop in this case even though it appears to be
int sum = 0;
for (int i = 0; i < 15; ++i)
  ++sum;
  std::cout << i << std::endl;
  
  
// Good Idea
// It's clear which statements are part of the loop (or if block, or whatever)
int sum = 0;
for (int i = 0; i < 15; ++i) {
  ++sum;
  std::cout << i << std::endl;
}

// Bad Idea
// hard to follow
if (x && y && myFunctionThatReturnsBool() && caseNumber3 && (15 > 12 || 2 < 3)) { 
}

// Good Idea
// Logical grouping, easier to read
if (x && y && myFunctionThatReturnsBool() 
    && caseNumber3 
    && (15 > 12 || 2 < 3)) { 
}

... <> is reserved for system includes.

// Bad Idea. Requires extra -I directives to the compiler
// and goes against standards
#include <string>
#include <includes/MyHeader.hpp>

// Worse Idea
// requires potentially even more specific -I directives and 
// makes code more difficult to package and distribute
#include <string>
#include <MyHeader.hpp>


// Good Idea
// requires no extra params and notifies the user that the file
// is a local file
#include <string>
#include "MyHeader.hpp"

...with the member initializer list

// Bad Idea
class MyClass
{
public:
  MyClass(int t_value)
  {
    m_value = t_value;
  }

private:
  int m_value;
};


// Good Idea
// C++'s memeber initializer list is unique to the language and leads to
// cleaner code and potential performance gains that other languages cannot 
// match
class MyClass
{
public:
  MyClass(int t_value)
    : m_value(t_value)
  {
  }

private:
  int m_value;
};

There is almost never a reason to declare an identifier in the global namespaces. Instead, functions and classes should exist in an appropriately named namespaces or in a class inside of a namespace. Identifiers which are placed in the global namespace risk conflicting with identifiers from other (mostly C, which doesn't have namespaces) libraries.

Compiler definitions and macros are replaced by the pre-processor before the compiler is ever run. This can make debugging very difficult because the debugger doesn't know where the source came from.

// Good Idea
namespace my_project {
  class Constants {
  public:
    static const double PI = 3.14159;
  }
}

// Bad Idea
#define PI 3.14159;

Ultimately this is a matter of preference, but .hpp and .cpp are widely recognized by various editors and tools. So the choice is pragmatic. Specifically, VisualStudio only automatically recognizes .cpp and .cxx for C++ files, plus vim doesn't necessarily recognize .cc as a C++ file.

One particularly large project (OpenStudio) uses .hpp and .cpp for user generated files and .hxx and .cxx for tool generated files. Both are well recongized and having the disctinction is helpful

const tells the compiler that a variable or method is immutable. This helps the compiler optimize the code and helps the developer know if a function side effects. Also, using const & prevents the compiler from copying data unnecessarily. Here are some comments on const from John Carmack.

// Bad Idea
class MyClass
{
public:
  MyClass(std::string t_value)
    : m_value(t_value)
  {
  }

  std::string get_value() 
  {
    return m_value;
  }

private:
  std::string m_value;
}


// Good Idea
class MyClass
{
public:
  MyClass(const std::string &t_value)
    : m_value(t_value)
  {
  }

  std::string get_value() const
  {
    return m_value;
  }

private:
  std::string m_value;
}

Raw memory access, allocation and deallocation, are difficult to get correct in C++ without risking memory errors and leaks. C++11 provides tools to avoid these problems.

// Bad Idea
MyClass *myobj = new MyClass;

// ...
delete myobj;


// Good Idea
std::shared_ptr<MyClass> myobj = make_shared<MyClass>();
// ... 
// myobj is automatically freed for you whenever it is no longer used.

Most portability issues that generate warnings are because we are not careful about our types. standard library and arrays are indexed with size_t. Standard containers sizes are reported in size_t. If you get the handling of size_t wrong, you can create subtle lurking 64bit issues that arise only after you start to overflow the indexing of 32bit integers. char vs unsigned char.

http://www.viva64.com/en/a/0010/

This includes statics and singletons

Global data leads to unintended sideeffects between functions and can make code difficult or impossible to parallelize. Even if the code is not intended today for parallelization, there is no reason to make it impossible for the future.

Much slower in threaded environments. In many or maybe even most cases, copying data is faster. Plus with move operations and such and things

include-what-you-use

This:

// some header file
class MyClass;

void doSomething(const MyClass &);

instead of:

// some header file



#include "MyClass.hpp"

void doSomething(const MyClass &);

This applies to templates as well:

template<typename T> class MyTemplatedType;

This is a proactive approach to simplify compilation time and rebuilding dependencies.

This is a general form of "Firewall Frequently Changing Header Files" and "Don't Unnecessarily Include Headers." Tools like BOOST_PP can be very helpful, but they also put a huge burden on the preprocessor

These are not meant to supercede good design

CCACHE, facebook's thing (warp)

Variables should be declared as late as possible, and ideally, only when it's possible to initialize the object. Reduced variable scope results in less memory being used, more efficient code in general, and helps the compiler optimize the code further.

// Good idea
for (int i = 0; i < 15; ++i)
{
  MyObject obj(i);
  // do something with obj
}

// Bad Idea
MyObject obj; // meaningless object initialization
for (int i = 0; i < 15; ++i)
{
  obj = MyObject(i); // unnecessary assignment operation
  // do something with obj
}
// obj is still taking up memory for no reason

... when it is semantically correct. Pre-increment is faster then post-increment because it does not require a copy of the object to be made.

// Bad Idea
for (int i = 0; i < 15; i++)
{
  std::cout << i << std::endl;
}


// Good Idea
for (int i = 0; i < 15; ++i)
{
  std::cout << i << std::endl;
}

Exceptions cannot be ignored. Return values, such as using boost::optional, can be ignored and if not checked can cause crashes or memory errors. An exception, on the other hand, can be caught and handled. Potentially all the way up the highest level of the application with a log and automatic restart of the application.

Stroustrup, the original designer of C++, makes this point much better than I ever could.

The combination of scripting and compiled languages is very powerful. It gives us the things we've come to love about compiled languages: type safety, performance, thread safety options, consistent memory model while also giving us the flexibility to try something new quickly without a full rebuild.

The VM based compiled languages have learned this already: jruby, jython, ironruby, ironpython

• chaiscript
• angelscript
• luabind
• SWIG

• http://geosoft.no/development/cppstyle.html
• http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml (Note that google's standard document makes several recommendations which we will NOT be following. For example, they explicitly forbid the use of exceptions, which makes RAII impossible.)
• http://www.parashift.com/c++-faq/
• http://www.cplusplus.com/
• http://sourceforge.net/apps/mediawiki/cppcheck/index.php?title=ListOfChecks
• http://emptycrate.com/