Question

My library uses several nested namespaces, laid out like the following:

Library name
    Class name 1
    Class name 2
    Class name 3
    [...]
    Utilities
        Class name 1
            [...]
        Class name 2
            [...]
        Class name 3
            [...]
        [...]

The “Utilities” namespace contains useful extensions to each of the classes that don’t warrant being included in the actual class itself.

The “Library name” namespace is necessary because it avoids broad conflicts with other libraries, the “Utilities” namespace is necessary to avoid the type of ambiguity that arises from things like this, and the “Class name” namespaces inside it avoid name clashes between utilities written for similar classes.

Despite this, it’s still an enormous hassle in practice. Take the following, for example:

MyLibrary::MyContainer<int> Numbers = MyLibrary::Utilities::MyContainer::Insert(OtherContainer, 123, 456);
// Oh God, my eyes...

This makes me think I’m doing something seriously wrong. Is there an easier way to keep things organized, intuitive and unambiguous?

Answer 1

Look at how the standard library (or boost) is organized. Nearly all of it is inside the single std namespace. There’s just little to be gained by putting everything inside its own namespace.

Boost puts most things inside boost, while major libraries get a single subnamespace (boost::mpl, or boost::filesystem, for example). And libraries commonly define a single aux subnamespace for internal implementation details.

But you don’t typically see deep or fine-grained namespace hierarchies, because they’re just painful to work with, and there’s little to no benefit from them.

Here are some good rules of thumb:

Helper functions related to a specific class should be in the same namespace as the class, to enable ADL to work. Then you don’t need to qualify the name of the helper function at all when calling it. (Like how you can call sort instead of std::sort on iterators defined in std).

For everything else, remember that the purpose of namespaces is to avoid name clashes and not much else. So all your library should be in a namespace, to avoid clashes with user code, but within that namespace, there’s no technical need for further subnamespaces unless you plan to introduce clashing names.

You may want to separate internals of your library into a sub-namespace, so users don’t accidentally pick them up from the main namespace, similar to Boost’s aux.

But generally, I’d suggest as few nested namespaces as possible.

And finally, I tend to make a point of using short, easy-to-type and easy-to-read names for my namespaces (again, std is a good example to follow. Short and to the point, and nearly always without further nested namespaces, so you don’t get a cramp from having to write it often, and so it doesn’t clutter your source code too much.)

Just the first rule about helper functions and ADL would allow your example to be rewritten like this instead:

MyLibrary::MyContainer<int> Numbers = Insert(OtherContainer, 123, 456);

Then we could rename MyLibrary to, say, Lib:

Lib::MyContainer<int> Numbers = Insert(OtherContainer, 123, 456);

and you’re down to something pretty manageable.

There shouldn’t be any clashes between similar utility functions for different classes. C++ allows you to overload functions, and specialize templates, so that you can have both an Insert(ContainerA) and Insert(ContainerB) in the same namespace.

And of course, clashes between namespaces and classes are only possible if you actually have additional nested namespaces.

Remember that within your Library namespace, you alone dictate which names are introduced. And so you can avoid name clashes just by, well, not creating any clashing names. A namespace to separate user code from library code is important because the two may not know about each others, and so clashes can occur unintentionally.

But within your library, you can just give everything non-clashing names.