SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsno-comments

no-comments

Coding & development

View repository

Updated 11-03 01:35

About this skill

No comments

Delete comments that describe our own code. Code we own should explain itself through names, types, and structure. Keep a comment only when it documents something outside our control that a reader could not learn from our code.

Scope

Use the files or diff the user named. Otherwise use the current diff against main, including staged, unstaged, and untracked changes:

git diff main...HEAD
git diff HEAD
git ls-files --others --exclude-standard

Only touch comments on lines added or modified in scope. Do not sweep untouched code in the same file.

Keep

A comment stays only if it is about an external system and is still accurate:

  • Browser behavior: Chrome/Safari/Firefox quirks, WebCodecs, Canvas, CSS, layout, event ordering, autoplay policy, linked bug trackers.
  • Media and tooling: FFmpeg, codecs, containers, Mediabunny, Chromium flags, Lambda/Cloud Run limits, Node.js, Bun, TypeScript compiler, bundler behavior.
  • Third-party libraries and APIs: why we call them in an unusual way, links to upstream issues.
  • OS, hardware, and spec constraints: file system, GPU, Linux/macOS/Windows differences, RFCs, W3C specs.

Also keep:

  • Machine-read directives: eslint-disable*, @ts-expect-error, @ts-ignore, /// <reference>, 'use client', istanbul ignore, prettier-ignore, biome-ignore, @vitest-environment, shebangs, license headers. Still check that each suppression is needed; remove dead ones.
  • JSDoc on public exported APIs (it surfaces in editor tooltips).
  • @deprecated tags (see the deprecate-api skill).
  • Comments in docs, MDX, and code snippets that are shown to users.

Delete

  • Narration of what the next lines do (// Get the frame, // Loop over tracks).
  • Restating names, types, or parameters.
  • Explanations of our own architecture, data flow, or design choices.
  • Defenses of workarounds for our own bugs. Fix the root cause in scope or leave the code uncommented.
  • IMPORTANT, do not remove, keep in sync with X, talk to Y first notes about our own code. If the constraint is real, offer to encode it (type, shared constant, test, lint) instead; delete the comment either way.
  • Commented-out code, TODO/FIXME without a linked issue, changelog-style notes (// Added in v4.0.x), and section dividers.

Mixed comments: keep only the external-system sentence and delete the rest.

If a comment hides a genuine surprise in our code, prefer a clearer name, extracted variable, or type over keeping the comment. Only reshape code when it is a trivial, local change; otherwise delete the comment and mention the surprise in the report.

Steps

  1. Collect every comment in scope (//, /* */, JSDoc, JSX {/* */}, # in shell/YAML).

  2. Classify each as keep or delete using the rules above. When unsure whether a comment is about an external system, check: would this still be true if we rewrote our code? If yes, keep. If it only makes sense because of how we wrote something, delete.

  3. Delete. Do not change behavior. Remove blank lines left behind that would break formatting.

  4. Run formatting and lint on touched packages:

    bunx turbo run lint --filter='<package-name>'

  5. Report: number of comments deleted, comments kept with a one-line reason each, any constraints offered for encoding, and any code surprises that deserve a follow-up.