File and Module Structure

Distinguish C++ Files From C Files

• C++ source file should be named .cpp or .cc NOT .c
• C++ header files should be named .hpp or .hh NOT .h

Include Guards In Header Files

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

#ifndef MYPROJECT_MYMODULE_HPP
#define MYPROEJCT_MYMODULE_HPP

namespace MyProject {

class MyClass {
};

}

#endif // MYPROJECT_MYMODULE_HPP 

It's good hygiene to add a comment at the end of #endif lines to document which #ifdef it is closing.

Use "" For Including Local Files

... <> 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"

[SM] The reason for <path/MyHeader.hpp> is two-fold:

• Search semantics for "MyHeader.hpp" are not fully specified in the language and thus create a potential portability problem. Search with <> is precisely specified. This is particularly important for cross-platform projects where you may want precise override control to pick up different headers depending on the platform/compiler (for a cleaner more maintainable approach than an #ifdef mess).
• Putting a namespace path in front of the header file name prevents header name collisions between the application and a library or 2 application namespaces.
• These reasons are why projects like Boost use the <boost/header.hpp> style.

[JT] Having just grepped through the boost source: there is a surprising amount of inconsistency within boost. Practically speaking, I have never seen a portability issue with using "" for includes, and have seen it solve far more problems then it has created. However if we do use the <> includes as you suggest, we need to be consistent and use fully scoped paths, like boost does, (real world example) boost/log/expressions/predicates.hpp:#include <boost/log/expressions/predicates/channel_severity_filter.hpp>

Forward Declare when Possible

This:

// some header file
class MyClass;

void doSomething(const MyClass &);

instead of:

// some header file
#include "MyClass.hpp"

void doSomething(const MyClass &);

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

Use Namespaces

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.

Name Resolution and the using Statement

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

Avoid using In C++ Implementation Files

This reduces the code readability.