namespace of C++ coding convention(C++编码规范之命名空间)

Although I am a Chinese man, to avoid unwilling misunderstanding,I write my summary in English.

Based on C++ Project experience and learning from some book about C++ coding convention, I try to make a conclusion,maybe there are some mistakes, I welcome that any nice guy can point them up.

Principles:

1.Name representing namespace should be all lowercase.

model::analyzer, io::iomanager, common::math::geometry

2.Create Unique Name Space Names

root that name at some naming authority, like the company name and division name.

3.Don't Globally Define Using

Don't place using namespace directive at global scope in a header file.Keep using statements to implementation files.

This actually means:

a. You may not use a using-directive to make all names from a namespace available.(But when you want to import the whole namespace you can do using-directive)

// Forbidden -- This pollutes the namespace.
using namespace foo;

b. You may use a using-declaration anywhere in a .cc file, and in functions, methods or classes in .h files.

// OK in .cpp files.
// OK in a function, method or class in .h files.
using ::foo::bar;

4. Unnamed namespaces are allowed and even encouraged in .cpp files, to avoid runtime naming conflicts:

namespace {                           // This is in a .cpp file.

// The content of a namespace is not indented
enum { kUnused, kEOF, kError };       // Commonly used tokens.
bool AtEof() { return pos_ == kEOF; }  // Uses our namespace's EOF.

}  // namespace

5. Named namespaces should be used as follows:

• Namespaces wrap the entire source file after includes:

  // In the .h file
  namespace mynamespace {
  
  class MyClass {
   public:
    ...
    void Foo();
  };
  
  }  // namespace mynamespace

  // In the .cc file
  namespace mynamespace {
  
  void MyClass::Foo() {
    ...
  }
  
  }  // namespace mynamespace

  The typical .cpp file might have more complex detail, including the need to reference classes in other namespaces.

  #include "a.h"
  
  class C;  // Forward declaration of class C in the global namespace.
  namespace a { class A; }  // Forward declaration of a::A.
  
  namespace b {
  
  ...code for b...         // Code goes against the left margin.
  
  }  // namespace b

• Do not declare anything in namespace std, not even forward declarations of standard library classes. Declaring entities in namespace std is undefined behavior, i.e., not portable. To declare entities from the standard library, include the appropriate header file.
• Namespace aliases are allowed anywhere in a .cpp file, anywhere inside the named namespace that wraps an entire .h file, and in functions and methods.

  // Shorten access to some commonly used names in .cpp files.
  namespace fbz = ::foo::bar::baz;
  
  // Shorten access to some commonly used names (in a .h file).
  namespace librarian {
  // The following alias is available to all files including
  // this header (in namespace librarian):
  // alias names should therefore be chosen consistently
  // within a project.
  namespace pd_s = ::pipeline_diagnostics::sidetable;
  
  inline void my_inline_function() {
    // namespace alias local to a function (or method).
    namespace fbz = ::foo::bar::baz;
    ...
  }
  }  // namespace librarian

  Note that an alias in a .h file is visible to everyone #including that file, so public headers (those available outside a project) and headers transitively #included by them, should avoid defining aliases, as part of the general goal of keeping public APIs as small as possible.

References:

Hoff, Todd (2007-01-09). "C++ Coding Standard : Naming Class Files".

C++: Quantum Leaps C/C++ Coding Standard

C++: C++ Programming/Programming Languages/C++/Code/Style Conventions

C++: GeoSoft's C++ Programming Style Guidelines

C++: Google's C++ Style Guide