Define new namespaces in C++

Creating a libraries in C++ and how to call it. Namespaces are a very important C++ language feature. This article present to you how to use and define the namespaces in the correct way.

First we have to know that Namespaces includes and wrap all enclosed names with another name. For example:

cpp code

namespace play{
    class Game{
        ...
    };
}

...

play::Game myGame;

By doing that, they make sure that if two libraries both implement the Game class, if they name their namespaces differently your program can use both without a conflict.

But this trigger another question. If two independent companies both decide to write Game Programming libraries, what are the chances that they are going to implement a class named Game? Is think the answer is most probably yes they may define a class with the same name.

We also like it when namespace names are easy to type, which means that they should be 3-6 characters long. With that in mind, what are the chances that both companies are going to name their namespace play? I think low probability.

From this it is clear that namespaces don't the end the problem by at least make it less probably to happens.

Here comes to solution which using a unique,long namespace names and then bring the namespaces into a program by using short aliases.

So a company writing the Game library library should write something like:


cpp code

namespace play_15863779 {
    class Game{
        ...
    };
}

The number associated with play_ has to be generated random algorithm. Say this code is placed in a header file called <playlib>Then the library is sold to a client, who decides to use it on a project. The client then writes his own project-local header file named <myplaylib>, with the following content:


cpp code

#include <playlib>


namespace play = play_15863779 ;

He has just created a project-local alias for the namespace of his library vendor. If the namespace name play had already been taken by another library, the user can choose another name: play2 or startGame.

How to start using the namespace:

A smart thing to do with your library is to make it easy for people to start using it. In an ideal world, they should be able to double-click on an installation file and the library would be immediately available inside their development environment. Next thing they are typing is #include <yourlib> and they are using it to do something useful.

However, if the user has to make his own header for every header in your library, then he has to suffer a little bit in order to use it. Not every user will be willing to do so.

The solution to this problem is to provide reasonable defaults, but to let the users cop out of them if they are not suitable. The way to do this is with pre-processor directives in your header file:

cpp code

namespace play_15863779 {
    class Game{
        ...
    };
}

#ifndef NO_PLAY_15863779_ALIAS
    namespace paly= play_15863779;
#endif

Here we provide a reasonable default for the namespace name. If that name is already taken, then the user can define the macro NO_PLAY_15863779_ALIAS and no alias will be defined.
Current Compilers

Error messages are already a nightmare with templates. With long namespace names, we make them even worse.

Unfortunately, none of the compilers I use are smart enough to display an error with the shortest available namespace alias at the point of error. So even though you may be using the alias play, if you make an error using the Game class the error will mention play_15863779::Game. Not very readable.

So I use a little trick. It works only for headers that contain only inline functions (as it affects the actual names used by the linker), but I have plenty of those. If the macro NO_PLAY_15863779_ALIAS is not defined, I use the short name as the namespace name, and the long name as the alias:

cpp code

#ifdef NO_PLAY_15863779_ALIAS
namespace play_15863779 {
#else
namespace play{
#endif
    class Game{
        ...
    };
}

#ifndef NO_PLAY_15863779_ALIAS
    namespace paly_15863779= play;
#endif

And the error messages become bearable again.