Skip to content
C.W.K.
Stream
Lesson 03 of 04 · published

Ordering Is an Ordering

~12 min · sorting, semantics, digest, restraint

Level 0Raw Ore
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"Ordering is an ordering, never a ranking of importance."

A sorted list is not innocent

The dashboard has a "what moved" panel: each series' newest reading beside the one before it, with the percentage change, sorted by the absolute size of that change. It is a genuinely useful thing to look at, and it is also the single most dangerous widget in the product.

The danger is not in the arithmetic — a percentage change is a fact. It is in what a human does with a vertical list. Readers do not experience a sorted list as "these are ordered by a quantity I could name." They experience it as a leaderboard. The top item feels like the most important item, and the feeling arrives before any conscious reasoning about the sort key.

So a surface that would never say "this is the most important change today" can say exactly that by accident, through layout alone, and be entirely truthful in every string it renders.

Two defenses, one soft and one hard

The soft defense is presentation. Show the sort key. Show both dates. Show the previous value beside the new one. Every extra visible fact competes with the leaderboard reading, because it makes the list look like a table of observations rather than a chart of winners.

The hard defense is in the code, and it is the one worth stealing: the function's own docstring states what the ordering is and is not. Descriptive by construction: a sorted list of magnitudes, no thresholds, no "alerts", nothing engineered to provoke. Ordering is an ordering, never a ranking of importance.

That sentence is not documentation. It is a constraint aimed at a future contributor who opens the file with a reasonable-sounding ticket — "highlight the top mover", "add a badge to the biggest change" — and would otherwise have no idea that the innocuous-looking sort is load-bearing.

Write the constraint where the temptation lives. The best place for a rule is not the architecture document; it is the docstring of the function somebody will be editing when they are about to break it. A rule three files away from the temptation loses every time.

The absent features are the design

Look at what the digest does not have. No threshold that promotes an entry. No color that escalates past a certain magnitude. No notification. No "unusual" flag. Each of those would be defensible on its own and each would convert an observation panel into a signal panel.

It also caps the list and reports how many pairs were compared. That is a small honesty: a list of twelve out of ninety-seven is a sample, and a sample presented without its denominator quietly implies it is the whole.

The same shape, elsewhere. This failure is not specific to finance. A log viewer sorted by duration reads as "these are your worst endpoints." An error dashboard sorted by count reads as "fix these first." Both are orderings by an observable quantity that readers experience as priority — and in both cases the fix is the same: show the sort key, show the denominator, and write down in the code that the order is not a judgement.

Code

The digest, with its constraint stated where an editor will see it·python
def digest(limit: int = 12) -> dict[str, Any]:
    """Each series' newest reading beside the one before it.

    Descriptive by construction: a sorted list of magnitudes, no
    thresholds, no "alerts", nothing engineered to provoke. Ordering is
    an ordering, never a ranking of importance."""
    ...
    moves.sort(key=lambda m: abs(m["change_pct"]), reverse=True)
    return {
        "generated_at": ...,
        "moves": moves[:limit],
        "compared": len(moves),   # the denominator, so 12 of 97
    }                             # cannot pass for all of them


# Each row carries what makes it checkable rather than dramatic:
#   value, previous, change_pct, from_date, to_date
#
# Note what is missing and had to be REFUSED, not merely skipped:
#   no `is_unusual` flag, no severity, no threshold colour,
#   no notification hook. Each one is a one-line addition.

External links

Exercise

Find a sorted list in a tool you use daily — slowest queries, largest files, most errors, top referrers. Ask two questions: does the interface state the sort key, and does it state the denominator? Then ask the harder one: if a reader treated position one as 'the thing to fix first', would that be right? Usually it is not, because the sort key and the priority are different quantities that happen to correlate.
Hint
The tell is a list where the top item and the item you should actually act on are frequently different. If you find yourself explaining to colleagues that 'the top one is not really the problem', the interface has been making a claim it never wrote down.

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.