Trim the prose: comments, punctuation, docs - #228
Merged
Conversation
The comments in this codebase had drifted into essays. A doc comment would state the rule, then argue for it, then restate the argument in different words, on the assumption that the reader needs convincing. They don't: the people reading this are the people who write it. Trim every comment to the claim plus whatever a future editor would get wrong without it. The kept rationale is the load-bearing kind -- why INTERVAL 0 HOUR cannot stand in for "no limit", why a blank banner text is read raw, why the response is re-resolved rather than echoed. What goes is the newsroom-workflow justification and the second pass at a point already made. Also replace the double hyphen everywhere it stood in for an em dash, in comments, test failure messages, docstrings and config. A comma, colon, semicolon or full stop always fits, and usually reads better: the dash was doing the work of not deciding which one was meant. Left alone where `--` is syntax rather than punctuation (shell flags, SQL line comments, the imported WordPress article bodies in init_schema.sql). Two user-facing blurbs shortened along the way, for the same reason: the "Breaking news" checkbox and the Settings section that describes it. No behaviour change. Build, vet, go test, tsc, vitest and the deploy script suite all pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L4qBhBdQto1yNp1zP7VLYc
Same problem as the comments, one level up. The docs explained the obvious at length and buried the operational detail inside it, so the paragraph you actually needed at 2am was three paragraphs down from a definition of blue/green. README: the first-time setup listed the repos it clones twice, and the frontend and Scalene run steps appeared in full under both First Local Run and Common Tasks. Deduplicated, folded setup into five steps, and linked docs/ETL-REBUILD.md, which nothing pointed at. deploy/README: slot ports are a table now instead of six bullets, and the deploy script's behaviour reads as a paragraph rather than an eleven-item list. Dropped one stale fact: it called Delta's root filesystem 15 GB, which HANDOVER 6.2 records as grown to 30 GB. HANDOVER: 6.2 is resolved, so it no longer needs thirty lines and a before/after table -- the lvextend/resize2fs pair and "the VG is now fully allocated" are the parts that still matter. frontend/README: was still the stock Vite template, down to the React Compiler notes and two ESLint config samples for a config we don't use. Replaced with the actual scripts and the one thing that catches people out: VITE_API_BASE_URL is empty, so /v1 goes through the dev server's proxy to https://localhost:8080 with secure:false, which is what tolerates the local self-signed cert. Every command, address, flag and gotcha is preserved; I diffed the inline code spans both ways to be sure. Documented script flags were checked against their argparse definitions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L4qBhBdQto1yNp1zP7VLYc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Language-only pass over the whole repo. No behaviour change, no API change, no
schema change.
Comments
Doc comments had grown into essays that argued for a rule after stating it,
then restated the argument. Trimmed to the claim plus whatever a future editor
would get wrong without it.
Kept the load-bearing rationale (why
INTERVAL 0 HOURcannot stand in for "nolimit", why a blank banner text is read raw rather than through
getSetting,why
PatchBreakingNewsre-resolves instead of echoing). Dropped thenewsroom-workflow justifications and the second pass at points already made.
Punctuation
Replaced the double hyphen everywhere it stood in for an em dash: comments,
docstrings,
t.Errorfmessages, config comments, UI copy. A comma, colon,semicolon or full stop always fit.
Left alone where
--is syntax, not punctuation: shell flags (npm run dev -- --port,git diff --exit-code -- docs), SQL line comments inschema/*.sql,and the imported WordPress article bodies in
init_schema.sql.Docs
the frontend/Scalene run steps appeared in full under both First Local Run
and Common Tasks. Also links
docs/ETL-REBUILD.md, which nothing pointed at.Corrects one stale fact: it called Delta's root filesystem 15 GB, which
HANDOVER §6.2 records as grown to 30 GB.
lvextend/resize2fspair andthe "VG is now fully allocated" warning, not the before/after table.
scripts and the thing that catches people out:
VITE_API_BASE_URLis empty,so
/v1goes through the dev server proxy tohttps://localhost:8080withsecure: false.Every command, address, flag and gotcha is preserved. I diffed the inline code
spans in both directions to confirm, and checked the documented script flags
against their argparse definitions.
Two UI blurbs
The "Breaking news" checkbox helper and the Settings section describing it were
three sentences each explaining what the banner is. Shortened.
Verification
go build ./...,go vet ./...,go test ./...,tsc --noEmit,vitest run(20 tests) and
deploy/scripts/deploy_scripts_test.shall pass.🤖 Generated with Claude Code
https://claude.ai/code/session_01L4qBhBdQto1yNp1zP7VLYc