Skip to content

CONCEPT Cited by 1 source

Symbol ID

A symbol ID is a stable, unique string identifier for a named code symbol (class, function, method, type, variable). The load-bearing property is stability under code motion: a symbol ID remains the same when the symbol's definition moves within the repository.

"The symbol ID can be used to link directly to the documentation page for the symbol, so there's a URL for every symbol that doesn't change even if the symbol's definition moves around." (Source: sources/2025-01-01-meta-indexing-code-at-scale-with-glean.)

Why stable IDs matter

  • Documentation URLs — auto-generated docs get a permanent URL per symbol; refactoring that moves a class between files doesn't break inbound links.
  • Cross-reference requests — tools ask for "all references to symbol X" against the symbol server without needing to know X's current file path.
  • Language-agnostic clients — the symbol ID lets a code browser behave uniformly even when each language has a different schema underneath.

Shape of a symbol ID

Per-language, not universal. From Meta: "the exact format for a symbol ID varies per language." The post's C++ example:

REPOSITORY/cpp/folly/Singleton

Pattern: <repo>/<language>/<qualified-name>. Other languages embed language-specific qualifiers (module, namespace, package, impl-of, overloading disambiguators).

Who owns the ID in Glean + Glass

  • Glean stores language-specific facts about the symbol (name, location, type signature, references).
  • Glass computes + assigns the symbol ID and exposes it through its symbol-server API.
  • The ID is the handle downstream tools (code browser, doc UI, references-finder) use to talk to Glass.

Trade-offs + failure modes

  • Language-qualified-name collisions. If two symbols can share a fully-qualified name (common in languages with function overloading or trait-impl duplication), the ID must include discriminators (parameter types, impl-of-trait, namespace) — implementation detail each language owns. The Glean post does not specify how each language disambiguates.
  • Symbol renames. Moving a symbol is cheap (ID stable); renaming a symbol changes its ID and breaks prior URLs. The post is silent on redirect handling.
  • ID vs span. The symbol ID is the handle; each query revision still needs fresh location data (file + line spans) because those do move. Symbol IDs and source spans are orthogonal.

Seen in

Last updated · 319 distilled / 1,201 read