C++ § scope

Scope and namespaces

C++ inherits C’s scope-and-linkage system and adds namespaces — named scopes that group declarations and admit nesting — and class scope, in which member names live and may shadow names from the enclosing scope. The full system is the substrate on which the One Definition Rule, the inclusion model, the modules system, and module-level encapsulation rest. Reading non-trivial C++ code requires fluency with the system; many of the language’s idioms — the using declaration, the unnamed namespace, the explicit std:: prefix, the friend mechanism — are direct consequences of the rules.

The kinds of scope

The standard names six kinds of scope:

Block scope — the curly-brace-delimited region in which a declaration appears. Function bodies, compound statements, and the loop-init clauses introduce block scope.
Function scope — the scope of goto labels. A label is visible throughout the function in which it appears.
Function prototype scope — the scope of parameter names in a function declaration that is not a definition.
Namespace scope — the scope of declarations at namespace (or global) level. The global scope is itself a namespace, often referred to as the global namespace.
Class scope — the scope of members of a class, struct, or union.
Template-parameter scope — the scope of template parameter names within the corresponding template.

Each scope nests inside an enclosing scope. A name in an inner scope shadows a name with the same identifier in an enclosing scope, until the inner scope ends.

int x = 0;                    // namespace scope (global)

namespace lib {
    int x = 1;                 // namespace scope (lib)

    class Widget {
        int x = 2;             // class scope

        void method() {
            int x = 3;         // block scope (function body)

            for (int x = 4; x < 10; ++x) {  // block scope (loop init)
                int x = 5;     // block scope (loop body)
                /* x is 5 here */
            }
            /* x is 3 here */
        }
    };
}

The successive shadowings are legal but discouraged in production code; the convention is to use distinct names where possible.

Namespaces

A namespace is a named region in which declarations live. Namespaces are the C++ mechanism for organising large codebases: each library (std, boost, the user’s own) declares its types, functions, and constants inside a namespace, and consumers refer to them through qualified names.

namespace company {
    namespace product {
        class Widget {
            // ...
        };

        Widget make_widget();
    }
}

company::product::Widget w = company::product::make_widget();

Nested namespaces and namespace aliases

C++17 admits a compact syntax for nested namespaces:

namespace company::product {
    class Widget;
    Widget make_widget();
}

Long namespace paths can be aliased:

namespace cp = company::product;

cp::Widget w = cp::make_widget();

The alias is a name in the enclosing namespace; it does not introduce a new namespace, only a shorter name for an existing one.

The `using` declaration and `using` directive

The using declaration brings a single name from another namespace into the current scope:

using std::cout;
using std::string;

cout << string{"hello"} << '\n';     // unqualified

The using directive brings every name from another namespace into the current scope:

using namespace std;                    // generally avoided

cout << string{"hello"} << '\n';

The using declaration is the conventional choice; the directive is broadly considered poor practice in headers and at namespace scope because it pollutes the calling code’s name resolution. The conventional advice:

Use using declarations for specific names (using std::string).
Use the directive only inside functions, where it is locally scoped.
Never use the directive at namespace scope in a header.

The unnamed namespace

A namespace with no name introduces a region whose contents are visible throughout the translation unit but invisible to any other:

// my_module.cpp

namespace {
    int helper(int x) { return x + 1; }    // visible only in my_module.cpp

    constexpr int kInternalSize = 42;
}

int public_function(int x) {
    return helper(x);
}

The unnamed namespace is the C++ replacement for static at file scope (the latter remains legal but is conventionally restricted to free functions and primitive globals; class types and templates require the unnamed namespace). The mechanism is the conventional way to declare module-internal helpers in modern C++.

The global namespace and `std`

The global namespace is the unnamed enclosing namespace. The scope-resolution operator :: without a left operand refers to it:

::global_function();           // explicit reference to the global namespace

The std namespace contains every standard-library declaration. Two conventions:

Always qualify: std::cout, std::string, std::vector<int>.
Add a using declaration in source files (not headers) for the small set of names used heavily.

The standard does not permit user code to add declarations to namespace std, with narrow exceptions: specialisations of standard templates may be added if the declaration would not be ill-formed.

Class scope

A class definition introduces a class scope. Members of the class are visible by their unqualified name within member functions and within other members:

class Counter {
public:
    void increment() { ++value_; ++total_increments_; }
    int  value() const { return value_; }

private:
    int        value_           = 0;
    static int total_increments_;
};

int Counter::total_increments_ = 0;     // definition outside the class

Outside the class, member names are accessed by qualification:

Counter c;
int n = Counter::total_increments_;     // static member
int v = c.value();                      // non-static member through an instance

Access control

Three access levels modify visibility within class scope:

public — accessible from any code.
protected — accessible from member functions, friends, and derived classes.
private — accessible from member functions and friends only.

class Widget {
public:
    Widget(int v);
    void public_method();

protected:
    void protected_helper();

private:
    int value_;
};

Access control is a visibility rule, not a trust rule: it does not prevent access through reinterpret_cast or other low-level mechanisms; it only prevents the compiler from generating code that would expose the member through ordinary means.

`friend`

A friend declaration grants another class or function access to the private and protected members of this class:

class Counter {
    friend class CounterAuditor;
    friend std::ostream& operator<<(std::ostream&, const Counter&);

private:
    int value_;
};

The conventional uses are operator overloads that need access to private members (commonly operator<<) and tightly-coupled helper classes. Friendship is not transitive, not inherited, and does not propagate: friend grants are explicit and narrow.

Linkage

Linkage applies to entities declared at namespace or class scope and governs whether the same name in different translation units refers to the same entity:

External linkage — every reference across all linked translation units refers to the same entity. The default for namespace-scope names that are not const and not in an unnamed namespace.
Internal linkage — every reference within a single translation unit refers to the same entity, but the name is invisible elsewhere. The default for const namespace-scope variables (since C++03), for names declared static at namespace scope, and for names in unnamed namespaces.
No linkage — the entity is unique per declaration. Block-scope names and most class-scope names have no linkage.

The interaction with storage class is largely as in C, with three additions specific to C++:

The unnamed namespace gives all its members internal linkage (effectively, but more flexibly than static).
const at namespace scope gives internal linkage by default; to give external linkage, use extern const.
inline (C++17 introduces inline variables) permits multiple definitions across translation units provided the definitions are identical; it is the standard mechanism for header-only constants and for defining non-const namespace-scope variables in headers.

The One Definition Rule

C++‘s One Definition Rule is more elaborate than C’s because of templates, inline functions, and inline variables. The principal rules:

Every entity used by a program must have exactly one definition across the whole program, with the exceptions below.
Inline functions, inline variables, templates, and class types may be defined more than once, provided each definition is in a different translation unit and the definitions are token-for-token identical after preprocessing.
Definitions of class members defined inside the class are implicitly inline.
Templates need not be definitions in the strict sense — the compiler instantiates them on demand from the template’s text, which it must see in every translation unit where the template is used.

The practical consequences:

Class definitions live in headers; the implicit inline of in-class member functions accommodates the multiple inclusion.
Function templates and class-template members are defined in headers because the compiler needs the body to instantiate them.
Non-inline non-template functions and non-inline non-template variables live in source files; the header declares them with extern (for variables) or with a prototype (for functions).

// counter.h
#pragma once
class Counter {
public:
    void increment() { ++value_; }      // implicit inline (defined in class)
    int  value() const;                 // declaration only

private:
    int value_ = 0;
};

inline constexpr int kInitialValue = 0;  // inline variable; OK in header

// counter.cpp
#include "counter.h"
int Counter::value() const { return value_; }    // single definition

Common patterns

Internal helpers in unnamed namespaces

// my_module.cpp
#include "my_module.h"

namespace {
    constexpr int kBufferSize = 4096;

    bool valid_input(const std::string &s) {
        return !s.empty() && s.size() < kBufferSize;
    }
}

void process(const std::string &input) {
    if (!valid_input(input)) return;
    /* … */
}

The unnamed namespace makes kBufferSize and valid_input invisible to any other translation unit; the convention has the same effect as static at file scope but extends to class types.

Selective `using` declarations

// inside a function or local block
void render(const std::vector<std::string> &lines) {
    using std::cout;
    using std::endl;
    for (const auto &line : lines) cout << line << endl;
}

The declarations are scoped to the function; they do not pollute the surrounding namespace.

Forward declarations to break header dependencies

// widget.h
class Renderer;            // forward declaration

class Widget {
public:
    void draw(Renderer &r);

private:
    int state_ = 0;
};

The pointer or reference to Renderer in Widget’s interface does not require the full definition of Renderer. The construction is the principal mechanism for reducing header coupling and for breaking circular dependencies.

Module-level encapsulation

C++20 modules (treated in Modules and translation units) provide a stronger form of encapsulation than namespaces and unnamed namespaces: a module exports an explicit list of names, and everything else is invisible to importers. The mechanism is the long-term replacement for the inclusion-model pattern of “header declares public interface, source defines everything plus internal helpers”; uptake is gradual as toolchains stabilise.