Dev.to WebDev 🛠 Dev 👁 0 📖 8 min read

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.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.