documenting-code-comments
1
总安装量
1
周安装量
#49980
全站排名
安装命令
npx skills add https://github.com/rileyhilliard/claude-essentials --skill documenting-code-comments
Agent 安装分布
amp
1
opencode
1
kimi-cli
1
github-copilot
1
antigravity
1
Skill 文档
Code Comments
Core principle: The best comment is the one you didn’t need to write.
Hierarchy
- Make code self-documenting (naming, structure)
- Use type systems for contracts
- Add comments only for WHY, never WHAT
When NOT to Comment
| Avoid | Why |
|---|---|
// Get the user's name |
Restates code |
@param {string} email |
Types already document |
| Stale comments | Misleading > missing |
When TO Comment
WHY, Not WHAT
// Use exponential backoff - service rate-limits after 3 rapid failures
const backoffMs = Math.pow(2, attempts) * 1000;
Gotchas and Edge Cases
// IMPORTANT: Assumes UTC - local timezone causes date drift
const dayStart = new Date(date.setHours(0, 0, 0, 0));
External Context
// Workaround for Safari flexbox bug (JIRA-1234)
// Per RFC 7231 §6.5.4, return 404 for missing resources
Performance Decisions
// Map for O(1) lookup - benchmarked 3x faster than array.find() at n>100
const userMap = new Map(users.map(u => [u.id, u]));
Refactor Before Commenting
| Instead of comment | Refactor to |
|---|---|
// Get active users |
const activeUsers = users.filter(u => u.isActive) |
// 86400000 ms = 1 day |
const ONE_DAY_MS = 24 * 60 * 60 * 1000 |
// Handle error case |
Extract to handleAuthError(err) |
TODO Format
// â
TODO(JIRA-567): Replace with batch API when available Q1 2025
// â TODO: fix this later
Audit Checklist
- Necessity – Can code be refactored to eliminate comment?
- Accuracy – Does comment match current behavior?
- Value – Does it explain WHY, not WHAT?
- Actionability – TODOs have ticket references?