8. Namespaces

Lesson 8 extension · names acquire meaning where lookup occurs

Which declaration does this name denote here?

Avoiding a collision is the visible benefit of a namespace. It is not the whole criterion. A useful namespace lets a caller state which component owns a name and lets a reader follow that meaning without searching the project for every declaration with the same spelling.

Namespace braces do not execute, allocate storage or create a runtime object. They contribute to the identity and lookup of names. A function can therefore be called update in two components without pretending that both operations mean the same thing. The qualification records the missing information.

#include <iostream>

namespace physics {
int update(int frame) {
    return frame + 1;
}
}

namespace rendering {
int update(int frame) {
    return frame + 2;
}
}

int main() {
    std::cout << physics::update(10) << '\n';
    std::cout << rendering::update(10) << '\n';
}

In physics::update(10), qualified lookup searches for update as a member of physics. That function returns 11. The next statement names rendering::update and returns 12. The repeated final name is not a defect to be eliminated. Each component offers an operation appropriate to its domain, while the caller states which domain it requires.

This also gives a design test that the compiler cannot complete. C++ can confirm that physics::update denotes a callable declaration. It cannot decide whether updating physics is the responsibility the program should invoke at this point. Qualification makes the ownership claim visible enough for a reviewer to challenge.

Lookup, linkage and linking answer different questions

These questions interact, but "namespace problem" is not a useful diagnosis for all three. A qualified call may identify exactly the intended declaration and still fail at link time because no built object supplies its definition. Conversely, two source files can compile separately and later contribute competing external definitions. The spelling of the namespace did not cause either missing or duplicated implementation.

Compilation of the example proves that each qualified call found a viable declaration and that the local definitions are valid in the translation unit. If the definitions were moved elsewhere and omitted from the link, qualification would remain correct while the completed program remained impossible to form. Correct lookup is necessary; it is not a substitute for the definition account from Lesson 7.

Make every reduction in qualification deliberate

A using declaration selects a particular name:

using physics::update;

const int nextFrame{update(10)};

Within its scope, unqualified lookup can now find the selected physics::update. The declaration can be useful where one domain is already obvious and repeated qualification would obscure the operation. Its scope should still be narrow enough that a reader can find the choice without inspecting distant files.

A using directive such as using namespace physics; makes namespace members available for unqualified lookup more broadly. It does not copy the namespace contents, import runtime code or make a program faster. It changes the candidate names that lookup may consider. If another directive makes rendering::update available as well, update(10) no longer states enough information and overload resolution can face two equally suitable candidates.

A using directive in a header is particularly intrusive. Every translation unit that includes the header receives the lookup effect in the surrounding context. A call can become ambiguous because of a decision made by a header the caller did not choose directly. Explicit qualification or a narrow using declaration in an implementation scope keeps the policy nearer the call that depends on it.

A successful unqualified call after adding a broad directive proves only that lookup and overload resolution found a candidate. It does not prove that the intended component was selected. If removing physics:: makes the code harder to review, the saved characters were not an improvement.

An alias changes the route, not the destination

A namespace alias gives another name to an existing namespace:

namespace engine_physics = company::engine::physics;

const auto nextFrame = engine_physics::update(currentFrame);

The alias does not copy declarations or create a second namespace object. engine_physics::update still denotes the member in company::engine::physics. The shorter route is useful when the original qualification is long and the alias remains clear in its local context.

An alias may also expose a selected implementation behind one name, but that choice is policy. If it is repeated through many source files, reviewers must reconstruct the selection from scattered declarations. Put the decision at a boundary where its meaning and build conditions can be inspected. Concision should not make ownership invisible.

Translation-unit-local names solve a different problem

An unnamed namespace at namespace scope gives its members internal linkage. I use it for helpers and state that belong only to the current translation unit and should not become part of the program-wide external interface. This is a decision about name identity across translation units.

Do not attach properties it does not provide. An unnamed namespace does not make mutable state thread-safe, does not create object-style privacy and does not prevent code in the same translation unit from naming its members where lookup permits. It says that another translation unit cannot refer to the same entity through external linkage.

Nested named namespaces serve organisation rather than internal linkage. Their depth should correspond to stable domains or components. Another :: is cheap to type and expensive to justify if it merely collects unrelated declarations. A deep path can reveal a useful ownership chain; it can also decorate a boundary that nobody can explain.

Run the lookup in three scopes

Use the physics and rendering example. First replace a qualified call with update(10) and add no using declaration. Predict what unqualified lookup can see. Next add using physics::update; in the smallest practical scope and predict the selected operation. Finally add using rendering::update; beside it and predict why the same call no longer states a unique choice.

For each version, record the declarations visible at the call, the compiler result and the operation the program requirement actually intends. Then create one different failure by declaring physics::update without linking its definition. The qualified name is now unambiguous, yet the program still fails. If your diagnosis changes from lookup to linking at the correct point, the namespace model is doing useful work.

const int nextFrame{physics::update(10)};

namespace physics {
int update(int frame); // declaration only
}

int main() {
    const int nextFrame{physics::update(10)};
    return nextFrame == 11 ? 0 : 1;
}