Frontend · Backend · Programmers

The Map Is Not the Terrain: Why Every Name in Software Is a Lie

By 勇宝趣学前端 · Jul 6, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams that treat a PRD, a variable name, or an architectural diagram as the full truth ship features nobody needs and debug symptoms instead of causes. The cost shows up as unused export buttons, refactors that swap one complexity for another, and incidents that drag on because the first plausible diagnosis was accepted too early.

Summary

A requirements document is not the requirement; an interface name is not the interface behavior. Drawing from the *Dao De Jing*, the argument is that every label in software—from a `status` field to a "microservices" architecture—is a simplification that can obscure messy, evolving reality. A user asking for an "export button" may actually need a report for their boss, just as a `GET /api/order/detail` endpoint may secretly be a backend control center.

Mature engineering and product work requires switching between two modes: observing without preconceptions to see what is actually happening, then narrowing with intent to define boundaries and act. Jumping straight to a familiar cause during an outage or accepting a feature request at face value both amount to mistaking the name for the thing itself.

Refactoring, tags, growth metrics—every term carries the same risk. A name makes a complex system discussable, but it also invites the team to stop looking. The discipline is to use names without being trapped by them, always asking what scenario, what cost, and what real behavior sits behind the label.

Takeaways

— A requirements document captures a named solution, not the user’s underlying problem; the real need is often discoverable only by asking why and in what scenario.

— Variable and interface names are historical simplifications—`isValid` or `/api/order/detail`—that hide dozens of edge cases and accumulated responsibilities.

— During incidents, suppressing the urge to immediately label the cause and instead systematically observing timing, scope, and dependencies leads to more accurate diagnoses.

— Product and engineering decisions benefit from alternating between open observation (seeing what is) and goal-driven convergence (deciding what to do).

— Refactoring is not inherently good; its value is measured by whether it reduces change cost, speeds up fault location, eases onboarding, or stabilizes core paths.

— Every technical buzzword—microservices, low-code, DDD—should trigger questions about team capability, user need, and domain clarity before adoption.

Conclusions

The article reframes a classic Daoist text as a practical debugging and product-discovery manual, arguing that the gap between a name and reality is the primary source of engineering waste.

Treating a user’s feature request as a solution rather than a signal of an unmet need is presented not as a junior mistake but as a fundamental category error that naming itself encourages.

The observation that a `status` field or a `detail` endpoint accumulates hidden responsibilities over time is a concise diagnosis of why legacy systems become brittle: the name stays the same while the behavior drifts.

By positioning refactoring as value-neutral—only its measurable outcomes matter—the piece pushes against the common engineering instinct to equate newness with improvement.

Concepts & terms

Dao vs. Name (道与名)

In the *Dao De Jing*, the Dao is the underlying, often ineffable reality of a thing, while the Name is the label or description we assign to it. The text argues that any fixed description is necessarily incomplete and can mislead if mistaken for the full truth.

Observing mysteries vs. observing manifestations (观其妙 vs. 观其徼)

Two complementary modes of investigation: observing without preconceptions to see a system’s full behavior, and observing with a specific goal to identify boundaries, constraints, and actionable paths. The article maps these to open-ended debugging and goal-driven product scoping.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗