In the real world, C++ projects can get very large. They can contain thousands of source files, being collaborated on by multiple teams of people.

In these scenarios, we need to be extra-mindful of how our project is organized. We don't want the work we're doing in our part of the program to conflict with or restrict what is possible in some other component.

For example, if we create a simple variable in one of our files, nobody else can create a variable with the same name, in any of the thousands of other files our program might contain.

Doing so would be a violation of the one definition rule, which we introduce later in this lesson. Both of the following files will compile successfully but, once the output is sent to the linker, it will notice the problem and raise an error:

1// SomeFile1.cpp
2float Pi{3.14};

1`// SomeFile2.cpp
2float Pi{3.14};

1SomeFile2.cpp.obj : error LNK2005: "float Pi" already defined in SomeFile1.obj

Another issue we'll encounter when working on such large projects is a simple human readability problem.

When we have a file that is creating an object from a Character class, or callling a function called CalculateArea(), which part of our project are those symbols coming from? When our project has dozens of components split across thousands of files, it's not always clear what we're using.

To solve both of these problems, we use namespaces.

Creating a Namespace

We can wrap sections of our code inside a namespace as shown below. Here, we create a namespace called Geometry:

1namespace Geometry {
2  // your code here
3}

We can populate namespaces with classes, functions, variables, and any of the constructs we've seen before:

1namespace Geometry {
2  float Add(float x, float y) {
3    return x + y;
4  }
5
6  float Pi { 3.14 };
7
8  class Square {
9    float SideLength { 5.0 };
10    float Area() {
11      return SideLength * SideLength;
12    }
13  };
14}

Test your Knowledge

Creating Namespaces

How can we create a namespace called Utilities?

Accessing Identifiers Inside Namespaces

As usual with { and }, namespaces define a new scope. Expressions within the namespace can access other namespace members as usual:

1namespace Geometry {
2  float Pi { 3.14 };
3  float Circumference(float Diameter) {
4    // We can access Pi here as we're in
5    // the same scope / namespace
6    return Diameter * Pi;
7  }
8}

To access namespace members from outside the namespace, we need the Scope Resolution Operator, which has two colons ::

For example, the following statement accesses the Add function and the Pi variable, which are both inside the Geometry namespace:

1namespace Geometry {
2  float Add(float x, float y) {
3    return x + y;
4  }
5
6  float Pi { 3.14 };
7}
8
9int main() {
10  Geometry::Add(10, Geometry::Pi);
11}

Test your Knowledge

The Scope Resolution Operator

How can we call the Greet function within the Utilities namespace?

1namespace Utilities {
2  void Greet() {
3    cout << "Hi!";
4  };
5};

Nested Namespaces

In particularly complex projects, even one of our namespaces can get extremely large, containing hundreds or thousands of identifiers. To solve this, we can essentially repeat the process - adding namespaces to our namespace.

That is, namespaces can be nested inside other namespaces. Below, we have a namespace called Constants within a namespace called Geometry:

1namespace Geometry {
2  float Add(float x, float y) {
3    return x + y;
4  }
5  namespace Constants {
6    float Pi { 3.14f };
7  }
8}

To access these nested identifiers, we can use the :: operator multiple times:

1Geometry::Add(10, Geometry::Constants::Pi)

The One Definition Rule (ODR)

Once we create a namespace and #include it in other files, we'll quickly begin to see linker errors relating to symbols already being defined. The following simple 3-file program recreates this:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  float Pi{3.14};
6  float Circumference(float Diameter) {
7    return Diameter * Pi;
8  }
9}

1// main.cpp
2#include "Geometry.h"
3
4int main() {}

1// SomeFile.cpp
2#include "Geometry.h"

1main.cpp.obj : error LNK2005: "float Geometry::Circumference(float)" already defined in SomeFile.obj
2main.cpp.obj : error LNK2005: "float Geometry::Pi" already defined in SomeFile.obj

To solve this, we can split our namespace into a header file and source file, in much the same way we have shown with classes.

Our declarations remain in Geometry.h whilst we move definitions to Geometry.cpp, as in the following example. Note we explain the meaning of extern in the next section:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  extern float Pi;
6  float Circumference(float Diameter);
7}

1// Geometry.cpp
2#include "Geometry.h"
3
4float Geometry::Pi{3.14};
5float Geometry::Circumference(float Diameter) {
6  return Diameter * Pi;
7}

The `inline` keyword

As of C++17, we also have the option of marking the members inline rather than moving their definition to a dedicated file:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  inline float Pi{3.14};
6  inline float Circumference(float Diameter) {
7    return Diameter * Pi;
8  }
9}

If the compiler receives multiple definitions of an inline member, it simply chooses one and discards the others.

This is intended to specifically solve multiple definitions caused by the #include directive. In such scenarios, it doesn't matter what definition the compiler chooses. All the definitions trace back to the same file (the file we're including) so they will all be the same.

We cover extern, inline, and related topics in more detail in the next course.

Class Declarations and the One-Definition Rule

A common point of confusion at this point is why our class definitions haven't infringed on the one definition rule when we include their headers in multiple files.

For example, it would seem like a class like this would generate multiple definitions of the Health variable when included in multiple files:

1// Character.h
2#pragma once
3
4class Character {
5public:
6  int Health{100}
7};

But when we define a class member in this way, the variable is not technically part of the class. It is simply a recipe for creating instances of a variable that will exist on objects created using the class.

On a namespace, however, we are generating a single variable, accessible using a specific identifier like Geometry::Pi. There will only ever be one instance of that variable in our program, so we can only have one definition for what its value should be.

It is possible to create class variables that behave like namespace variables. These are called static class members, which we'll introduce in the next course.

Adding to Namespaces

In complex projects, namespaces can get quite large. They can include multiple classes, for example. As such, it is common for the contents of a namespace to span multiple files.

Below, we create a namespace containing two classes, where each class is declared within a dedicated file:

1// Square.h 
2#pragma once
3
4namespace Geometry {
5  class Square{};
6}

1// Circle.h 
2#pragma once
3
4namespace Geometry {
5  class Circle{};
6}

1// main.cpp
2#include "Circle.h"
3#include "Square.h"
4
5int main() {
6  Geometry::Circle MyCircle;
7  Geometry::Square MySquare;
8}

Where we're providing a full declaration of our namespace within a header file, we can alternatively provide class definitions by including that header file and then using the :: operator like this:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  class Circle;
6}

1// Circle.h
2#pragma once
3#include "Geometry.h"
4
5class Geometry::Circle {
6
7};

When our class is within a namespace, our source files for that class can provide function definitions using either the namespace syntax, or the :: operator:

1// Square.h
2#pragma once
3
4namespace Geometry {
5  class Square{
6   public:
7    float Area();
8    float Perimeter();
9
10  private:
11    float SideLength;
12  };
13}

1// Square.cpp
2#include "Square.h"
3
4// Option 1:
5namespace Geometry {
6  float Square::Area() {
7    return SideLength * SideLength;
8  }
9}
10
11// Option 2:
12float Geometry::Square::Perimeter() {
13  return SideLength * 4;
14}

Anonymous Namespaces

Previously, we introduced the concept of global variables. These are variables that are added to our files, outside of any scope. In the following example, Pi is a global variable:

1// main.cpp
2float Pi;
3
4int main() {}

We saw how the linker can link a definition in one file to its use in another.

However, this presents a problem when there are multiple definitions of the same identifier.

For example, if we create a global Pi variable in another file, our program will no longer link correctly:

1// Geometry.cpp
2float Pi;

1main.cpp.obj : error LNK2005: "float Pi" already defined in Geometry.obj

This is again a violation of the one-definition rule (ODR).

If we intend to forward-declare a variable that will be defined in some other file, we can add the extern keyword as described above:

1// Geometry.cpp
2float Pi { 3.1415 };

1// main.cpp
2#include <iostream>
3using namespace std;
4
5extern float Pi;
6
7int main() {
8  cout << "Pi as defined in some other file: "
9    << Pi;
10}

1Pi as defined in some other file: 3.1415

If we intend to create a variable that we can use anywhere in the current file, without affecting any other file, we can solve the problem using an anonymous namespace.

Predictably, an anonymous namespace is a namespace without a name:

1namespace {
2  float Pi { 3.14 };
3}

Identifiers defined within an anonymous namespace are only available to the same source file where the namespace exists.

Therefore, we can think of an anonymous namespace as the "private" section of a file.

1// Geometry.cpp
2namespace {
3  float Pi{3.1415};
4}
5
6float GetPi() { return Pi; }

1// main.cpp
2#include <iostream>
3using namespace std;
4
5namespace {
6  float Pi{3.14};
7}
8
9// Forward declaring a function defined
10// in Geometry.cpp
11float GetPi();
12
13int main() {
14  cout << "Pi in main.cpp: " << Pi
15    << "\nPi in Geometry.cpp: " << GetPi();
16}

1Pi in main.cpp: 3.14
2Pi in Geometry.cpp: 3.1415

Summary

This lesson provided an introduction to namespaces, covering their creation, usage, and significance in organizing code.

Key Takeaways:

How to create and use namespaces to organize code and avoid identifier conflicts.
The role of the scope resolution operator :: in accessing namespace members.
The concept of nested namespaces and how they can be used for further organization.
The importance of the One Definition Rule (ODR) in namespaces and strategies to adhere to it using the extern and inline keywords.
The distinction between namespaces and classes in C++, and the introduction to anonymous namespaces for file-specific usage.

Namespaces