code-comment-writer
Writes precise, reader-oriented code comments explaining "why" not "what". Covers onboarding, refactoring, algorithm explanation, tech debt marking, and API integration scenarios. Should be used when the user mentions adding comments, documenting code, explaining code logic, improving code readability, or needs help understanding code during handoff. Distinguished from refactoring skills which focus on code structure changes.
- License 许可
- MIT
- 最近更新
- 2026-04-18
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- code-comment-writer
- boundary
- { "vs_react-component-refactor": "react-component-refactor focuses on restructuring code, this skill focuses on adding explanatory comments" }
- category
- coding
- description
- Writes precise, reader-oriented code comments explaining "why" not "what". Covers onboarding, refactoring, algorithm explanation, tech debt marking, and API integration scenarios. Should be used when the user mentions adding comments, documenting code, explaining code logic, improving code readability, or needs help understanding code during handoff. Distinguished from refactoring skills which focus on code structure changes.
02 资源文件 1
- 参考文档references/diagram-guide.md3.7 KB
03 SKILL.md 正文
Code Comment Writer
Core Capability
Write precise, targeted code comments that explain the "why" behind code, not the "what". Comments should help future readers (including yourself) understand intent, edge cases, pitfalls, and migration context.
When to Use
- Onboarding: Help new team members understand legacy code
- Refactoring: Mark migration context and known pitfalls
- Algorithm Explanation: Document complex logic decisions
- Tech Debt: Mark code that needs future attention
- API Integration: Explain external dependencies or quirks
When NOT to Use
- Don't explain what the code literally does (e.g.,
// increment ifori++) - Don't add comments for self-documenting code
- Don't add redundant comments that duplicate the code
Reading Scenarios
This skill supports multiple reading scenarios:
| Scenario | Focus | Example |
|---|---|---|
| Onboarding | Why this code exists, what's tricky | "This cache has a 5min TTL because..." |
| Refactoring | Migration notes, what to watch for | "TODO: remove after users migrate to V2" |
| Algorithm | Why this approach was chosen | "Using binary search because data is sorted" |
| Tech Debt | Why it's a problem, how to fix | "Slow because no index; add index in V2" |
| API Integration | Quirks, error handling | "Throws on 400, caller must handle" |
Comment Types
1. Intent Comments
Explain why the code does what it does.
// Using batch insert because single insert causes
// lock contention at high concurrency.
// TODO: switch to streaming after DB upgrade.
async function saveBatch(items: Item[]) { ... }
2. Edge Case Comments
Document known boundaries.
// Handles empty string as valid input (matches legacy behavior).
// Max length: 10000 chars (DB constraint).
function normalize(input: string) { ... }
3. Pitfall Comments
Warn about surprising behavior.
// WARNING: This mutates the original array.
// Use clone() first if that's not intended.
function process(items) { ... }
4. Migration Comments
Track transition state.
// DEPRECATED: Use v2 API instead.
// Will remove after Q3 2024 deprecation deadline.
// TODO(team-backend): remove in V3.0
async function legacyFetch(id: string) { ... }
5. Diagram Comments (ASCII)
Use when logic flows are complex — see references/diagram-guide.md.
/*
* Payment flow
*
* User clicks pay
* │
* ▼
* Validate inventory ──fail──▶ Show error
* │ success
* ▼
* Create order ──...
*/
const handlePay = async () => { ... };
Quality Guidelines
- Be specific:
// retry up to 3 timesis better than// retry logic - Include context: Mention external constraints or past incidents
- Use TODO/FIXME/Deprecation markers for actionable items
- Reference tickets when possible:
// See JIRA-1234 - Keep comments in sync: Outdated comments are worse than none
Anti-Patterns
| Anti-Pattern | Why It's Bad |
|---|---|
// increment i |
Restates what code does |
// check if null |
Obvious from code |
// TODO: fix this later |
Not actionable |
| Commented-out code | Just delete it |
Relationship to References
references/diagram-guide.md— When and how to use ASCII diagrams in comments
04 同仓库更多 Skills
meeting-minutes
Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps.
documentation-writer
Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.
doc-coauthoring
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
code-review-workflow
Executes comprehensive 4-phase code review: basic review, quality check, bundle analysis, and test coverage. Should be used when the user mentions comprehensive code review, checking code quality, or reviewing staged changes with multi-phase analysis. This is the comprehensive review workflow, distinct from focused skills like frontend-code-review, staged-code-review, or code-change-test-designer.
code-change-test-designer
Analyzes code changes and designs comprehensive test cases. Reads diffs, summarizes capability changes, and designs test cases covering main flows and edge cases. Should be used when the user mentions test coverage, designing tests for code changes, or analyzing diff/commit for testing purposes. Distinguished from code-review-workflow which provides comprehensive review, this skill focuses on test case design for code changes.
skill-creator
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.