How and Why to use Namespaces

Namespaces are a feature of C++ which address the problem of name conflicts. There is a “global” namespace, where everything lives which was declared without namespace. Especially the Arduino environment declares a huge amount of variables and constants there, so it is a good practice to put everything you write in a own namespace. Namespaces are only used at compile time, and they do not use any memory at runtime or make your program slower.

In my case I choose the namespace lr which stands for Lucky Resistor. Everything I declare in this namespace is accessible trough the :: operator which you probably already know from function definitions.

namespace myone {

class MyClass {
};

} // end namespace

myone::MyClass myClass;

As long you are inside of a namespace declaration, you do not have to add the given prefix:

namespace myone {

class MyClass {
public:
    MyClass(); // ctor
};

MyClass::MyClass() {
    // ...
}

} // end namespace

How to use Classes and Types from a Namespace

If I like to use a class which is defined in its own namespace, I can choose to always prefix the types with the namespace or just import all names into the global namespace. Usually it is a good idea to prefix everything, to make clear from where you use a type. But sometimes importing the objects in the global namespace make things more readable. You can also import just a few types into the global namespace. You see there are endless possibilities.

As an example I will use the following class which is defined in the header file “MyClass.h”. Below I show you how to access the classes in different ways.

#pragma once

namespace myns {

class MyClass {
public:
    enum State {
        On,
        Off
    };
public:
    MyClass();
    void doWork();
    void setState(State state);
};

extern MyClass gMyClass; // global instance.

} // end namespace

The header declares the class MyClass in the namespace myns and also a global instance of this class called gMyClass, which is often used in Arduino libraries.

One way to access everything is just be prefixing all types with the namespace:

#include "MyClass.h"

setup()
{
    // Create a own instance of the class
    myns::MyClass myClass;
    myClass.doWork();
    myClass.setState(myns::MyClass::On);
    // Use the global instance.
    myns::gMyClass.doWork();
    myns::gMyClass.setState(myns::MyClass::Off);
}

To simplify things, you can import single types or names into the global namespace. After the using myns::MyClass you can use the class MyClass without the need to prefix it with the namespace name. But the variable gMyClass was not imported, therefore you have to add the prefix for this variable.

#include "MyClass.h"

using myns::MyClass;

setup()
{
    // Create a own instance of the class
    MyClass myClass;
    myClass.doWork();
    myClass.setState(MyClass::On);
    // Use the global instance.
    myns::gMyClass.doWork();
    myns::gMyClass.setState(MyClass::Off);
}

Now you could just add every name like this:

using myns::MyClass;
using myns::gMyClass;

Or simple import the whole namespace:

#include "MyClass.h"

using namespace myns;

setup()
{
    // Create a own instance of the class
    MyClass myClass;
    myClass.doWork();
    myClass.setState(MyClass::On);
    // Use the global instance.
    gMyClass.doWork();
    gMyClass.setState(MyClass::Off);
}
[/code]

Why this Prevents Naming Conflicts

For example you wrote a Stream which controls the flow of water in the stream of your model railway project. You write a header as shown the the example below.

#pragma once

class Stream
{
    // ...
};

If you try to compile this code, you will get an error message.

Stream.h:4:7: error: redefinition of 'class Stream'

One solution would be to rename you class, but you really like the name, or renaming would lead to even more conflicts. If you are using namespaces you will never run into these problems.

#pragma once

namespace myns {

class Stream
{
    // ...
};

}

Using your Class

If you use your library, you can choose to import your whole namespace into the global namespace. The conflicts are not gone of course, but you can selectively add prefixes where required.

#include "myns/Stream.h"
#include "myns/Train.h"
#include "myns/Signal.h"

using namespace myns;

setup()
{
    Train train;
    train.start();
    myns::Stream stream; // conflict, use prefix.
    stream.maximumFlow();
}

See also: How and Why to Avoid Preprocessor Macros

Learn More

Event-based Firmware (Part 1/2)

You start with small, simple firmware. But with each added feature, the complexity grows and grows. Soon, you need a good design in order to maintain the firmware and ensure the code remains clean and ...
Read More

Extreme Integers – Doom from Below

As a beginner or immediate C++ programmer, you heard never mixing unsigned and signed integer types or avoiding unsigned integers at all. There was also this talk about undefined behaviour. Yet, in embedded software development, ...
Read More

How and Why to Avoid Preprocessor Macros

While most naming conflicts in C++ can be solved using namespaces, this is not true for preprocessor macros. Macros cannot be put into namespaces. If you try to declare a new class called Stream, but ...
Read More

Write Less Code using the “auto” Keyword

The auto keyword was introduced with C++11. It reduces the amount of code you have to write, reduces repetitive code and the number of required changes. Sadly, many C++ developers are not aware of how ...
Read More

How to Deal with Badly Written Code

Sadly there is a ton of badly written code out in the wild. Hardware related code, seem to suffer more in this regards. I imagine, many developer in this segment are unwillingly to invest time ...
Read More

Guide to Modular Firmware

This article is for embedded software developers with a solid working knowledge of C or C++, but who struggle with large and complex projects. If you learn to develop embedded code, e.g. using the Arduino ...
Read More