Comment lists fewer members than exist

What goes wrong

A comment or document enumerates the members of a set and presents the enumeration as the whole of it, while the code holds more. The reader treats the written list as the inventory and reasons, tests, or changes only the members named, never learning that others exist.

Example

A class comment lists the three places that read a record without a guard; a fourth was added later, so anyone weighing the cost of removing the guard counts three and misses one.

Not to be confused with

Not a documented guarantee the code fails to keep, where prose states a behaviour and the behaviour differs; here the prose states membership and the set has outgrown it.

Discovered by

@sks24git GitHub

Field notes · 13

@sks24git2026-11-04beat 1 review round

A block of settings documentation is moved verbatim to a new home, and it still leaves out one setting the code reads. The move carries the old gap along, so readers trust a list that is incomplete.

Check a moved list against its source of truth. A verbatim move keeps every old omission.
Generate option lists from code when you can. Hand lists drift.

@sks24git2026-11-03

A privacy page gained a new item it collects, but the retention list on the same page was left as it was. A reader cannot tell whether that data is deleted at once or kept for years.

Touch the retention list whenever you add a collected item. What you collect and how long you keep it drift apart one edit at a time.

@sks24git2026-10-28

A rule catalog claimed to list everything the system bumps into, and its test only compared rows that were already in it. A live timeout rule was missing, so the model priced a world where idle work is never released.

Start a completeness test from the source, not the list. Missing rows are invisible to a list-driven check.
Say 'as today' only after reading today's code. Base assumptions age fastest.

@sks24git2026-10-24

A plan deferred five items to after a pilot, and the change that listed the deferred work copied four and dropped the fifth. Once the pilot ends, tickets are filed from that list, so the dropped item is never built.

Diff the list against its source before merging. A copied list is where ideas quietly die.
Carry the gate with the item. A deferred task keeps its "after X" or it runs before X exists.

@sks24git2026-09-12beat 1 review round

A comment named the callers of a shared rule. A later change moved half of them onto another form of it and left the sentence, so the next reader reasons about callers that are gone.

Move a reader, fix the sentence naming it. Code moves; prose never follows by itself.
A stale pointer is free until the next edit, which it then misleads.

@sks24git2026-09-11

An inventory of the columns a job may overwrite omitted two of them, and the list of events it may emit was short by two as well. Both were extended by later migrations nobody re-read.

An inventory in prose needs a date and a source query.
Re-derive the list at each edit; migrations only add.

@sks24git2026-09-11

An enumeration was copied from a note written months earlier. The schema had grown to three times as many values since, and the shortest list is the one everybody quotes.

Copy an enumeration from the schema, never from prose about it.
A stale list is quoted more often than the source.

@sks24git2026-09-10beat 4 review rounds

A doc block that presents itself as the enumeration of a column's allowed values named three, while the same change set four in the constraint. The next reader writing a positive filter drops one silently.

A list claiming to be exhaustive must be diffed against the constraint. Cite the version you actually shipped.
A missing case in an enumeration is a missing branch.

@sks24git2026-09-10

A table comment claimed every write happens only while one flag is on, and listed the writers. A merge from the base added another writer, gated by a different flag, and the promise stood.

Re-read prose that enumerates writers after every merge. The base branch can add a writer your own diff never touched.

@sks24git2026-09-10

A doc comment listed every thrower of an exception, built from a search run before the change. The same diff added one more, so the list shipped looking complete and already wrong.

A list produced by a search is stale the moment you edit. Re-run it on the final head, or name the command that produced it.

@sks24git2026-09-10beat 2 review rounds

A doc comment named one place that raises a given conflict; a a search tool of the tree found four, two of them on money paths. Callers written to that comment handle one case and drop the rest.

Enumerate with a command before writing 'the only'. A count from memory ages badly and reads as established fact.

@sks24git2026-09-10beat 2 review rounds

A class comment listed every path that reads a table with no feature flag, and the diff added a fourth without updating it. Anyone judging the cost of disarming the flag reads three and misses the user-facing one.

A census in a comment is a promise of completeness. Extend it in the same diff that adds a member, or delete it.

@sks24git2026-09-04beat 3 review rounds

A comment explained why a branch was safe, and the reason was wrong while the branch was right. The next reader builds on the reason, so the fix deletes a guard the code still needs.

Check reasons, not just branches. A right branch with a wrong reason passes review and misleads later work.
Cite by name, not line number. Lines rot when someone rewrites the file.