6,395 lines of comments in our repo, zero TODOs, and 22 citations of a spec file that was deleted the day after it was written
A comment is the only part of a codebase nothing enforces. Tests fail, types complain, linters shout, and a comment just sits there being true until one day it is not. So I counted every comment in the repository behind
A comment is the only part of a codebase nothing enforces. Tests fail, types complain, linters shout, and a comment just sits there being true until one day it is not. So I counted every comment in the repository behind PubTrivia, pulled out the ones that assert something a stranger could check from outside, and checked them.
Fourteen were checkable. Twelve still hold. Two are wrong, and a third points at a file that was deleted on 9 June.
The census
Parsed with a line scanner over git ls-files '*.ts' '*.tsx':
| Measure | Value |
|---|---|
| Files | 462 |
| Lines | 62,249 |
| Code lines | 50,691 |
| Comment lines | 6,395 (10.3 per cent) |
| Blank lines | 5,163 |
| Comment blocks | 2,303 |
| Words of comment | 51,665 |
JSDoc openers (/**) |
971 |
| Files with no comment at all | 99 of 462 |
| Longest single comment | 3,019 characters |
By directory, the density is not where you would guess:
| Directory | Files | Comment lines | Code lines | Ratio |
|---|---|---|---|---|
utils |
47 | 1,282 | 3,173 | 28.8% |
scripts |
1 | 21 | 51 | 29.2% |
lib |
27 | 1,124 | 3,810 | 22.8% |
ws-server |
16 | 427 | 1,588 | 21.2% |
__tests__ |
26 | 425 | 3,253 | 11.6% |
hooks |
2 | 60 | 489 | 10.9% |
app |
210 | 1,833 | 22,884 | 7.4% |
components |
125 | 1,150 | 15,251 | 7.0% |
app and components are three quarters of the code and a tenth commented, because most of those files are page copy. The money, the database clients and the shared libraries run three to four times denser, which is the right shape: comments cluster where the decisions were hard.
Zero TODOs
TODO 0
FIXME 0
HACK 0
XXX 0
Not one, in 2,303 blocks. That is not virtue, it means the backlog lives somewhere other than the source. What the comments carry instead is argument: 168 blocks contain "only", 107 "never", 60 "must", and 124 a backward-looking phrase such as "used to" or "no longer". That last group matters, because a comment explaining what the code used to do ends up as the only record of a decision nobody remembers.
247 em dashes
This product has a house rule: no em dashes in anything a reader sees. It holds, exactly, across the live site:
$ curl -s https://pub-trivia.app/faq | grep -c $'\xe2\x80\x94'
0
A codepoint census a week ago put it at zero across all 111 pages, against 469 hyphens. Inside the comments, 247 blocks contain an em dash. The rule covers published copy, so this is not a violation, but it shows where a style rule stops: once text is no longer rendered, the author writes the way they actually write.
22 citations of a file that does not exist
Eleven files carry comments that cite requirement numbers:
utils/game/validation.ts:34 * Requirements: 3.3, 3.4
ws-server/src/index.ts:14 // ─── Req 11.2: Validate required environment variables ───
ws-server/src/shutdown.ts:11 * Register SIGTERM and SIGINT handlers for graceful shutdown (Req 11.7).
ws-server/src/healthHandler.ts:8 * Liveness check for deployment infrastructure (Req 11.5)
22 citations in total. The document they cite was .kiro/specs/quiz-hosting-engine/requirements.md, and git has the whole story:
$ git log --all --format='%h %ad %s' --date=short --diff-filter=A -- \
.kiro/specs/quiz-hosting-engine/requirements.md
7536513 2026-06-08 made changes and started implementation
$ git log --all --format='%h %ad %s' --date=short --diff-filter=D -- \
.kiro/specs/quiz-hosting-engine/requirements.md
fae4811 2026-06-09 finished of the tasks
224 lines, added one day, deleted the next, and the numbers it assigned are still being cited five months later in the files that implement it. "Req 11.5" is now a reference to a thing that only exists in a commit nobody will go and read. The repository's only surviving document is docs/seo-plan.md.
The claims I could actually check
A comment that says "we do it this way because the pooler drops the connection" is an explanation, and I cannot falsify it from a terminal. But some comments assert a fact about the running product, and those are testable. All fourteen I found, with how I checked them:
| Comment | Claim | Verdict |
|---|---|---|
components/FeaturesGrid.tsx:14 |
the grid is 1 column, then 2, then 3 | holds |
lib/indexnow.ts:19 |
the key is a UUID with the dashes removed | holds |
lib/routes.ts:62 |
the key file must skip the auth gate or verification gets a redirect | holds |
app/too-many-requests/page.tsx:7 |
an HTTP 200 page whose body says 429 | holds |
app/sitemap.ts |
the three legal pages fall back to the build date | holds |
components/content/SourceNote.tsx:18 |
the date is human-readable, "September 2026" | holds |
components/tools/ScoresheetGenerator.tsx:40 |
the bounds stop a typo asking for a 900-page PDF | holds |
lib/tools/quiz-night-poster.ts:66 |
only Latin-1 plus Windows-1252 punctuation can be drawn | holds |
ws-server/src/index.ts:90 |
the library default would accept 100 MB frames | holds |
lib/pricing/plans.ts:36 |
Pro is one host account at thirty pounds a month | holds in code, not on my screen |
lib/admin/system.ts:111 |
an older deploy answers 404 on the stats endpoint | holds, and is now historical |
components/mascot/types.ts:1 |
once one mascot is chosen the others can go | still waiting, four remain |
app/compare/redtooth-alternative/page.tsx:10 |
that competitor's old domain is a for-sale page | stale |
tailwind.config.ts:6 |
content globs for ./pages and ./src
|
stale |
Four of the twelve that hold, checked out loud:
$ curl -s https://pub-trivia.app/ | grep -c 'grid gap-px border sm:grid-cols-2 lg:grid-cols-3'
1
$ curl -s https://pub-trivia.app/2382c7da66fd467eb45e9c97aadf605a.txt | wc -c
32
$ curl -s -o /dev/null -w '%{http_code}\n' https://pub-trivia.app/too-many-requests
200
$ curl -s https://pub-trivia.app/too-many-requests | grep -o '429' | wc -l
2
$ curl -s https://pub-trivia.app/sitemap.xml | grep -c 'T00:00:00'
108
That last one is the sitemap comment holding: 108 of 111 URLs carry a date somebody wrote down, and the three that do not are the three legal pages with no registry node, which take the build clock instead.
The SourceNote example value is not a hypothetical either. Fourteen pages pass a checkedOn string, seven of them "September 2026" and seven "November 2026", and the September ones are on the page right now:
$ curl -s https://pub-trivia.app/compare/kahoot-for-pub-quiz | grep -c 'September 2026'
2
The two that are wrong
The competitor's domain. A comment at the top of one comparison page explains the editorial decision behind it and adds, in passing, that the competitor's old domain "no longer belongs to them (it was a for-sale page when we checked)". Today that domain answers 200 with this:
$ curl -sL https://redtooth.com/ | grep -o '<title>[^<]*'
<title>Unlocking the Power of Redtooth: Revolutionizing Your Online Experience
Not a for-sale page any more. Generated filler on a bought domain, which is a third state the comment never considered. The page itself is fine, because it links to the product's real current site and not to that domain, and the dated "Where this comes from" box on the page tells readers when we looked. The comment is the only part that aged badly, and this is exactly the failure mode of a comment that describes somebody else's website.
The Tailwind globs. tailwind.config.ts tells Tailwind to scan four directories for class names:
content: [
'./pages/**/*.{ts,tsx}',
'./components/**/*.{ts,tsx}',
'./app/**/*.{ts,tsx}',
'./src/**/*.{ts,tsx}',
],
$ ls -d pages src
ls: pages: No such file or directory
ls: src: No such file or directory
Half the list names directories this project has never had, because the file came from a template. It is configuration rather than a comment, but it fails the same way: a statement about the repository that nothing checks. It is harmless, it costs nothing at build time, and it has been wrong since June.
Three more of this kind were already published here in earlier posts and I am not re-deriving them: a copyright line whose comment promises the year is passed in by the caller, in a function that takes no arguments; an SEO module whose comment documents a title template the code stopped using; and a comment promising sixteen table cards from a sheet that produces four.
The comments worth keeping
The census makes one thing obvious. The good comments in this repository are not descriptions, they are arguments that would otherwise be lost:
- The pricing module explains why exchange rates are hard-coded rather than fetched: a live feed would move a customer's price between two page loads.
- The maintenance switch explains why it is a constant in a file rather than an environment variable or a database flag: the database is the thing that is down.
- The content registry opens by explaining that three route lists used to be maintained separately and disagreed, which is the whole justification for the file existing.
- The longest comment, 3,019 characters, is about which countries a sale is routed through, and it is long because getting it wrong means mis-charging tax.
None of those are checkable from outside, and they are the reason utils and lib are commented at four times the rate of components.
What this audit cannot see
Fourteen checkable claims out of 2,303 blocks is 0.6 per cent. Everything else is intent, rationale or a description of code that sits beside it, and a comment that says why cannot be proved wrong by curl. That is a limit of the method, not a verdict on the comments.
The 99 files with no comments are also invisible to this exercise. A missing comment cannot be stale, which makes "zero wrong comments" an achievable score for anybody willing to write none.
And my parser is line-based, not an AST walk. It counts the closing line of a block comment, treats a comment trailing a line of code as a block but not as a comment line, and skips anything inside a string that looks like //. The 6,395 is therefore accurate to within a few dozen lines, and I would not defend the last digit. The TODO count is a plain regex over the extracted text and that one I would defend: there are none.
The fix list this produced
Delete the 22 requirement citations or restore the 224-line document they point at. Drop the two dead Tailwind globs. Rewrite the sentence about somebody else's domain as a dated observation, the way the page's own source box already does it. And the general one: a comment that describes the outside world needs a date in it, because a reader five months later has no other way to know whether to trust it.
The pages all this is about are live. The comparison cluster is at pub-trivia.app/compare, the scoresheet and poster tools at pub-trivia.app/tools, and the product is free to start with no card at pub-trivia.app.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.