How to mitigate class declaration being far from its owner namespace declaration in a file?

Question

So, I've seen how useful namespaces can be to organize declarations into their respective groups, but now comes an issue with this.

The difference between making a library in C and a library in C++ is in C you must prefix your declarations with what they belong to, for example a library we'll dub MyMath might have a vector class, well the name might be MM_Vector.

In C++, you would have a namespace MyMath with a Vector class declared as a part of it.

Now the difference here is in C, just by going to the class declaration you immediately know how to use it. In C++, you would have to check which namespace a particular class belongs to (really only a problem in files where the declaration isn't near the namespace declaration, which can be common if there are constants and enumerations declared between the two). While I prefer using a namespace for organization, in my opinion this is still a valid argument as an annoyance.

What have people done to reduce this annoyance?

Answer 1

Use an IDE that provides quick tips and symbol navigation and/or use document generators (e.g. Doxygen).

Answer 2

There shouldn't be a problem. Just make sure there are never using statements in any header, and don't have monolithic source files. If it's a big problem, fully qualify your classes.

Answer 3

The problem you describe boils down to the mindset you're in. When developing the code, you know darn well that you're using the MyMath::Vector, so you're interested in seeing as little clutter as possible, and add a using namespace MyMath; or using MyMath::Vector; clause.

Just after a couple of months, someone drops into your code, and doesn't know what namespace the Vector is coming from. He might argue (as you did) that this using declaration makes the code less comprehensible.

And that is where the good IDE comes in: you can leave namespace (which can become quite large, really, for big systems) out, but when debugging/editing the code, the IDE can perfectly hint you where the symbol was declared, defined, referenced etc...

Answer 4

"only a problem in files where the declaration isn't near the namespace declaration, which can be common if there are constants and enumerations declared between the two)."

If that bothers you, do this:

namespace MyMath {
    constants and enumerations go here
}

namespace MyMath {
    class goes here
}

namespace MyMath {
    another class goes here
}

Unlike a class, you don't have to define a namespace all together. The brackets don't mean "this is everything there is", they just denote a scope in which all definitions are into that namespace, and all symbols are looked up in the namespace.

Answer 5

In chapter 8 of his book, Stroustrup recommends a style such as the following:

MyMath.h

namespace MyMath {
  class Vector;
};

Vector.h

#include "MyMath.h"

class MyMath::Vector {
  public:
  Vector();
  // ...
};

Vector.cc

#include "Vector.h"

MyMath::Vector::Vector() { /* ... */ }

Limiting open namespace-declarations to declarations of their contents produces brief summaries. Fully-qualified definitions allow the compiler to catch typos.

As applied to your concern, class declarations and definitions in this style make plain the parent namespace of each class—at the expense of what the Go folks call stuttering.