AGENT SKILL

commenting-standards

Comment writing, formatting, and wrapping rules for all TypeScript code in agenteq.

License 许可
MIT
所属仓库
sunchayn/agenteq
最近更新
2026-10-29
Stars
★ 7
Forks
0

01 前言 Front Matter

name
commenting-standards
description
Comment writing, formatting, and wrapping rules for all TypeScript code in agenteq.

03 SKILL.md 正文

Commenting Standards

Applies to every comment in this codebase.

1. Core principle

Comment why, not what. Skip a comment that only restates the next line.

  • Do comment: non-obvious decisions, workarounds, reasoning behind choosing one approach over another.
  • Do not comment: obvious code, step-by-step narration.
  • Do not reference a ticket, issue, or user request. A comment must stand alone for a reader with no such context.
  • Do not reference a previous version of the code or how this version differs. Tells: "instead", "now", "no longer", "used to", "previously", or a clause defending an absence ("with no X of its own"). After a refactor, check each touched comment makes sense to someone who never saw the old file. If it only parses as a contrast with removed code, cut that clause or the comment, and keep only the plain remaining fact. Contrast belongs in a commit message or PR description.

2. Language

  • No metaphors, idioms, or narrative framing. Plain language tied to concrete technical facts.
  • Name variables and data structures directly.
  • No colon or semicolon joining two independent clauses. Use two sentences.
  • Wrap only at a period or comma, never mid-sentence.
  • Use the existing technical term, not a paraphrase. Write "what tag HEAD is pointing at", not "the tag the branch is sitting on".

3. Doc blocks and inline comments

  • Class or function doc block: always expanded multi-line /** ... */, never single-line, even when short.
  • Doc block stays conceptual: what the function achieves, its contract. No variable names, no internal control flow steps. Those go in an inline comment at the line they explain.
  • Doc block prose: max 4 lines. Shorten or use a list.
  • Inline // comment: max 3 lines. Shorten, or move the explanation to the doc block.
  • Last line of a multi-line comment, block or inline: at least 4 words. Rebalance wrapping instead of leaving a short trailing fragment.

4. Current gap

Many files lack inline why-comments on non-obvious branches and decisions (why this order, early return, fallback). That is not the target state. Backfill why-comments in any file you touch. Do not copy the sparse state.

5. Related Skills

04 同仓库更多 Skills