Best practices for referring to other namespaces in header files

[Johan Nilsson]

[ This is a slightly modified re-post from c.l.c++.m ]

I've seen many alternatives when it comes to referring to types defined
in parent/sibling/other namespaces. Consider the following hypothetical
namespace layout:

namespace company {

namespace lib {

class SomeClass {};

namespace module1 {

class SomeOtherClass {};

} // module1

namespace module2 {

...

} // module2

} // lib

} // company

In a header file, from inside company::lib::module2, what would be the
preferred way to refer to:

1. std::vector
2. company::lib::SomeClass
3. company::lib::module1::SomeOtherClass

I've got a few alternatives myself:

1(a) '::std::vector'
1(b) 'std::vector'

2(a) '::company::lib::SomeClass'
2(b) 'company::lib::SomeClass'
2(c) 'lib::SomeClass'
2(d) 'SomeClass'

3(a) '::company::lib::module1::SomeOtherClass'
3(b) 'company::lib::module1::SomeOtherClass'
3(c) 'lib::module1::SomeOtherClass'
3(d) 'module1::SomeOtherClass'

Each one of the the alternatives has its pros and cons in terms of
readability and stability (not being affected by someone e.g.
introducing company::lib::module2::SomeClass in combination with
alternative 2(d) above).

What do you do in practice (assuming you do use nested namespaces)? I'd
especially appreciate comments backed by some real-world experience
maintaining libraries/applications.

// Johan

 

[Siemel Naran]

In a header file, from inside company::lib::module2, what would be the
preferred way to refer to:

1. std::vector
2. company::lib::SomeClass
3. company::lib::module1::SomeOtherClass

I've got a few alternatives myself:

1(a) '::std::vector'
1(b) 'std::vector'

(1b) seems most standard, as std::vector is so common.

2(a) '::company::lib::SomeClass'
2(b) 'company::lib::SomeClass'
2(c) 'lib::SomeClass'
2(d) 'SomeClass'

3(a) '::company::lib::module1::SomeOtherClass'
3(b) 'company::lib::module1::SomeOtherClass'
3(c) 'lib::module1::SomeOtherClass'
3(d) 'module1::SomeOtherClass'

(2d), (3d), the minimal solutions seem best to me.

Each one of the the alternatives has its pros and cons in terms of
readability and stability (not being affected by someone e.g.
introducing company::lib::module2::SomeClass in combination with
alternative 2(d) above).

Stability is not an issue, as there will likely be compile errors.
Readibility is best. Besides, it seems best design that only namespaces at
the same level use the same names -- so if there is a
company::lib::module2::SomeClass then there can be a
company::lib::module1::SomeClass, but there probably should not be a
company::lib::SomeClass as this opens up the stability issue you just
mentioned.

 

[Johan Nilsson]

[snip]

2(a) '::company::lib::SomeClass'
2(b) 'company::lib::SomeClass'
2(c) 'lib::SomeClass'
2(d) 'SomeClass'

3(a) '::company::lib::module1::SomeOtherClass'
3(b) 'company::lib::module1::SomeOtherClass'
3(c) 'lib::module1::SomeOtherClass'
3(d) 'module1::SomeOtherClass'

(2d), (3d), the minimal solutions seem best to me.

Each one of the the alternatives has its pros and cons in terms of
readability and stability (not being affected by someone e.g.
introducing company::lib::module2::SomeClass in combination with
alternative 2(d) above).

Stability is not an issue, as there will likely be compile errors.
Readibility is best. Besides, it seems best design that only namespaces at
the same level use the same names -- so if there is a
company::lib::module2::SomeClass then there can be a
company::lib::module1::SomeClass, but there probably should not be a
company::lib::SomeClass as this opens up the stability issue you just
mentioned.

That was actually what I meant with stability - protect oneself (and
users) against such future changes. OTOH, there's the readability
issue. Not many people seem to care, or they simply don't use
namespaces that much, so I guess I'll have to use common sense and just
make up my mind.

Currently leaning towards always using fully qualified names, without
the global namespace prefix.

// Johan

 

[Siemel Naran]

Siemel Naran wrote:

That was actually what I meant with stability - protect oneself (and
users) against such future changes. OTOH, there's the readability
issue. Not many people seem to care, or they simply don't use
namespaces that much, so I guess I'll have to use common sense and just
make up my mind.

Currently leaning towards always using fully qualified names, without
the global namespace prefix.

It might be hard to enforce, because if one of the programmers forgets the
prefix (which could happen in a large project), the code will compile and
we'll never know there was a coding standards violation. Also, I imagine
the violations would be difficult to catch in a code review. One could
write a tool to catch such coding violations though.

One may somehow use namespace aliases (to typedef one namespace to another)
to simplify things, but I've never done it before, so don't know firsthand.