Skip to content

chore: trim code comments across the repo - #7

Merged
fleizean merged 1 commit into
developfrom
chore/trim-comments
Oct 19, 2026
Merged

fleizean merged 1 commit into
developfrom
chore/trim-comments

Conversation

@fleizean

Copy link
Copy Markdown
Member

Summary

Cuts the code comments down across the backend, frontend, tests, deploy scripts, workflows and container/nginx config. Comment-only change: no code, configuration values or behaviour change.

Why

Many comments narrated what the next lines do, restated method names, labelled sections, or described one specific package, incident or earlier change instead of the code. They made files longer and went stale quickly. The reasoning behind a change belongs in its pull request, not in the code.

Changes

  • Removed narration, section labels (// ---- Helpers ----, <!-- Header -->), commented-out code, and history notes ("previously…", requirement IDs, phase names)
  • Removed examples that named specific packages, sites, versions or dates
  • Removed XML doc (///) and JSDoc (/** */) blocks, following the project convention of no doc comments
  • Removed references to the deleted docs/ops/ runbooks
  • Long file headers reduced to one to three lines
  • Kept, as one short line: comments that explain a non-obvious reason (concurrency and cancellation rules, security limits, SSR/accessibility constraints, empty catch blocks, deliberate Dependabot holds)
  • 290 files, +387 / −1886 lines

Notes for reviewers

  • Kept untouched on purpose: the header lines that usage() prints in deploy/deploy.sh, deploy/remote.sh and deploy/backup.sh (sed -n '2,8p' / '2,7p'), the # vX.Y.Z comments after pinned action SHAs (Dependabot reads them), tool directives, and anything inside strings, heredocs or inline templates.
  • The long operational headers of the deploy scripts and workflows (environment variable lists, the authorized_keys forced-command example, the secret list) are gone. The script usage() texts still describe each command.
  • Every changed line was checked to be a comment or blank line. The only exceptions are code lines that lost or shortened a trailing comment, with the code text unchanged. Line endings and BOMs are unchanged.
  • Not built or run locally; CI is the check.

Checklist

  • The pull request targets develop and is about one thing
  • Commit messages follow Conventional Commits (feat(scope): ..., fix(scope): ...)
  • CI is green (backend tests, frontend build and tests, dependency gate)
  • Schema changes are EF Core migrations generated by the tool, not hand-edited
  • A changed backend DTO has its TypeScript twin updated in src/frontend/src/app/core/models
  • New dependencies are justified and their lock files are updated in the same commit
  • No secrets, tokens or personal data in code, logs or this description
  • Code comments are kept to a minimum; the reasoning lives in this description

Remove comments that narrate the code, restate names, label sections or
describe one specific package, incident or earlier change. XML doc and
JSDoc blocks go too. Comments that carry a non-obvious reason are cut
to one short line. No code changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fleizean
fleizean merged commit e675f7e into develop Oct 19, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant