documenting-code-comments
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
More from rileyhilliard/claude-essentials
design
Enforces precise, minimal design for dashboards and admin interfaces. Use when building SaaS UIs, data-heavy interfaces, or any product needing Jony Ive-level craft.
18writer
Writing style and tone guide for human-sounding content. Use when writing documentation, READMEs, commit messages, PR descriptions, blog posts, or any user-facing content.
17strategy-writer
Produces executive-quality strategic documents in The Economist/HBR style. Use when writing strategy memos, market analysis, business cases, customer research reports, or any document for Product, Design, and Business leaders. Customer-led, evidence-based, narrative-driven.
13systematic-debugging
Debugging framework that finds root causes before proposing fixes. Use when investigating bugs, errors, unexpected behavior, failed tests, or when previous fixes haven't worked.
13executing-plans
Executes implementation plans with smart task grouping. Groups related tasks to share context, parallelizes across independent subsystems.
12refactoring-code
Improves code structure while preserving behavior through test verification. Use when cleaning up code, reducing duplication, simplifying complexity, or reorganizing modules.
12