vvkit-writing-comments
Use when writing or reviewing comments and doc comments, or when a diff adds explanatory prose alongside code.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- vvkit-writing-comments
- description
- Use when writing or reviewing comments and doc comments, or when a diff adds explanatory prose alongside code.
03 SKILL.md 正文
Writing comments
The default is no comment. Names and structure carry the meaning; a comment is for what they provably cannot. Where the project has a convention, follow the project.
Codex runtime
Load referenced skills by reading their SKILL.md. Surveyor, reviewer and runner
skills are role instructions, not registered agent types or enforced tool allowlists.
Use a generic subagent only when delegation is available and permitted; otherwise
perform the role inline. Follow the active session's model, context and permission
rules. User authorization takes precedence over imported workflow approval gates.
Claude hooks and plugin commands are not active in this package. Existing
.claude/context/ paths refer to project documents, not Codex configuration.
The one test
- A comment answers why, and the why is not obvious from the code beside it.
- Describes what the code does: delete it. Recoverable from the next three lines: delete it.
- Code that needs a comment to be followed needs a better name or a smaller function instead.
Limits
| Kind | Limit |
|---|---|
| Line comment | 1 line |
| Member doc comment (function, property, case) | 1 line. A second only for a genuinely subtle exception |
| Type-level doc comment (class, struct, enum, protocol, module) | Several lines, to orient a reader about the whole type |
Over the limit means cut, not reflow — the second sentence usually restates the first.
Never
- Narrate — "loop over the items", "set the title", "returns nil when empty".
- Restate the signature — a parameter doc repeating the name and type.
- Decorative dividers. A structured section marker the language supports is fine.
- Migration history — "moved from X", "new in the refactor". Git knows.
- Ticket ids. In public API docs they leak an internal tracker.
- Commentary on the change. Describe the code as it stands, not how it got there.
When a doc comment is warranted
| Declaration | Doc comment |
|---|---|
| Public or exported | Yes — it is the contract, and exempt from the member limit where the contract needs the words |
| Internal helper with a non-obvious exception | Yes — one line naming the exception |
| Internal helper self-evident from its name | No |
| Override or conformance with no added behavior | No |
| A constant whose value encodes a decision | Yes — why this value |
Existing comments
- Never delete an existing comment or TODO unless asked. These rules govern what you write, not what you remove.
- Never overwrite an existing doc comment. Add where missing; reconcile only when the contract changed.
Self-check
Every multi-line comment block you just added:
git diff -U0 | awk '/^\+ *(\/\/|#|--)/{n++; if (n>1) print; next} {n=0}'
Empty output, or only type-level overviews, passes. Anything else is over the limit until you can name why that block earns a second line.
04 同仓库更多 Skills
no-heading
Use when proving that the validator rejects a body with no H1 and a force-loading @-link.
wrong-name-does-not-match-dir
Dispatches a subagent per task and reviews between each one.
writing-tests
Use when adding or changing behavior, fixing a bug, or judging whether an existing or generated test earns its place.
writing-skills
Use when authoring or editing a skill, agent, command or hook for this kit, or when deciding whether a piece of guidance belongs in a skill at all.
writing-project-instructions
Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.
writing-logs
Use when adding or reviewing log statements, or when deciding what level a message belongs at.