Skip to content
C.W.K.
Stream
Lesson 02 of 05 · published

Never Borrow the Famous Name

~12 min · naming, precision, disclosure, definitions

Level 0Raw Ore
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"It is the largest N US listings, which is what an index of that shape approximates too. Never called 'the S&P 500'."

The temptation after the approximation is accepted

Having agreed to compute the measure from available data rather than licensed data, there is a second decision immediately behind it, and it is easy to get wrong because it feels like a labeling detail.

What do you call it? Everybody knows the famous index. Calling it "S&P 500 concentration" would be instantly understood, would look professional, and would be a small lie that costs nothing today.

The refusal is explicit in the code for this measure: it is never called that. The measure is stated as what it is — the top ten companies as a share of the largest N US common stocks by market cap — and the borrowed name is left on the shelf.

Scope that sentence carefully, because the same repository has a counterexample one module over. A composite indicator built on the same broad-market ETF proxy is named "S&P 500 P/E", and that name is served in the API payload and rendered on the dashboard. So this is a discipline the product holds in the place it was argued about and has not yet applied everywhere — which is worth knowing, because it is the honest state of most such rules. A naming discipline is not adopted the day it is written; it is adopted one grep at a time.

What a borrowed name silently imports

The reason is not pedantry. A famous name carries a specification, and adopting the name adopts claims your computation does not satisfy.

A real index has an explicit membership rule, a committee that applies it, an eligibility test, defined treatment of dual listings and foreign domiciles, a published rebalancing schedule, and a float-adjusted weighting method. "The largest 500 by market cap" has none of that. The two sets overlap heavily and are genuinely not the same set, and their differences are exactly the kind that show up in a concentration number.

So a reader who sees the famous name reasonably concludes they can compare the figure against a published one from a data vendor. They cannot. When the numbers differ, they will assume one of the two is broken — and the actual answer, that these are different measures wearing one name, is the only answer nobody will consider.

A name is an API contract. Reusing a well-known name imports its whole specification, including the parts you did not implement and have never read. If your computation differs from the canonical definition in any way a user could notice, give it a name that describes what you actually did — the small awkwardness of a longer label is nothing beside the cost of a comparison that silently should not have been made.

Where the description lives

The definition does not live only in documentation. It rides in the source string of every stored row, spelled out with the actual counts and the date the measurement describes.

That placement is the same principle as carrying a percentile's window on its row, applied to a definition rather than a caveat. A row extracted into a spreadsheet, quoted in a delegation brief, or read by a future consumer arrives carrying its own definition. Nobody has to have been present for the naming discussion to know what they are looking at.

The name also constrains the future. A measure honestly called "the top ten of the largest 500 US common stocks" can have its universe size changed to 1,000 with a source-string change and no lie. A measure called "S&P 500 concentration" cannot change anything without becoming more wrong, because the name has pinned it to somebody else's specification — one you do not control and cannot follow.

Code

The measure stated in the code, and in every row it writes·python
# The measure is stated plainly and computed from what the paid
# plan actually carries:
#
#     top 10 companies by market cap, as a share of the largest N
#     US common stocks by market cap
#
# Never called "the S&P 500". It is the largest N US listings,
# which is what an index of that shape approximates too.

UNIVERSE_SIZE = 500   # the shape of the index everyone pictures,
TOP_N = 10            # without claiming to BE it

gauges.store_row(
    GAUGE, "us", SERIES, day, round(share, 3),
    f"derived:top{TOP_N}/top{len(universe)} US common stock"
    f" by market cap @ {day}")

# The stored source string carries the definition, the actual
# counts, and the session date -- so a row read anywhere, by
# anyone, arrives knowing what it measures.

External links

Exercise

Audit the names of three metrics your team publishes. For each, ask whether the name matches a definition someone outside your team would recognize, and whether your computation matches that definition exactly. Where it does not, rewrite the name to describe your computation and put the definition into the payload rather than a wiki page.
Hint
The highest-risk names are the ones borrowed from finance, statistics, or standards bodies — 'churn', 'p99', 'availability', 'active user', 'conversion'. Every one has a canonical meaning somewhere, and every one is routinely computed slightly differently while keeping the name that promises otherwise.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.