write-comments
Writes explanatory comments to code to improve readability for developers and AI systems. Use when documenting code or improving code comprehension.
When & Why to Use This Skill
This Claude skill automates the generation of high-quality, intent-focused code documentation to enhance software maintainability. It analyzes complex logic and structures to provide meaningful explanations of the 'why' and 'how' behind implementation details, ensuring codebases are easily understood by both human developers and AI-assisted systems.
Use Cases
- Legacy Code Documentation: Quickly clarify the purpose and intent of inherited codebases to reduce technical debt and simplify maintenance.
- Developer Onboarding: Accelerate the ramp-up process for new team members by providing clear, standardized explanations of complex functions and business logic.
- AI-Ready Codebases: Optimize source code for better interpretation by AI agents and LLMs by providing explicit context and structural metadata.
- Code Quality Standardization: Enforce consistent commenting styles and formatting rules across a project to ensure professional and readable documentation.
| name | write-comments |
|---|---|
| description | Writes explanatory comments to code to improve readability for developers and AI systems. Use when documenting code or improving code comprehension. |
Write Comments to Code
Your primary objective is to clarify the code's purpose and intent for a new developer. If the code is self-evident, do not add a comment.
Process
- Analyze the code to understand its structure and functionality
- Identify key components, functions, loops, conditionals, and any complex logic
- Add comments that explain:
- The purpose of functions or code blocks
- How complex algorithms or logic work
- Any assumptions or limitations in the code
- The meaning of important variables or data structures
- Any potential edge cases or error handling
Formatting
- Every comment must start with a capital letter and end with a period.
- Multi-line docblocks (
/** ... */) must have the/**and*/on their own, separate lines.
Content and Placement
- Docblocks (
/** ... */): Use for all exported members (functions, types, hooks, constants) and complex internal logic. Explain what the item is for. - Single-line (
//): Use for brief, inline explanations of non-obvious implementation details or to label logical sections within a function. - Focus on the "why" and "how" rather than just the "what".
- Preserve the original code's formatting and structure.
- Do not change the code's functionality.
Deletion Mandates
- DELETE any comment that merely restates what the code does (e.g.,
// Increment counter). - DELETE all commented-out code blocks. Use version control for history.