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
- General TypeScript conventions: write-typescript-code
04 同仓库更多 Skills
writing-commit-messages
Conventions for writing commit messages in this repo.
★ 7
review-checklist
Checklist to run through before approving a pull request.
★ 7
writing-commit-messages
Conventions for writing commit messages in this repo.
★ 7
laravel-pint
Formats PHP code with Laravel Pint before a commit.
★ 7
laravel-pint
Formats PHP code with Laravel Pint before a commit.
★ 7
example-skill
Example skill synced by agenteq
★ 7