| name | writing-code-comments-and-docstrings |
| description | Generates inline code comments and documentation strings. Use when writing function/class documentation, explaining complex logic, adding TODO/FIXME annotations, or documenting APIs in code. |
Writing Code Comments and Docstrings
Quick start
Collect or infer:
- Programming language and documentation conventions
- Code element type (function, class, module, method)
- Target audience (internal team, external consumers, future maintainers)
- Complexity level of the code being documented
- Whether public API or internal implementation
Then produce output using TEMPLATES.md. Validate with RUBRIC.md.
Workflow
- Identify documentation type: docstring (API), inline comment (implementation), or annotation (TODO/FIXME).
- Determine what the code does vs. why it exists—document the latter.
- For docstrings: document parameters, return values, exceptions, and side effects.
- For inline comments: explain non-obvious decisions, constraints, or workarounds.
- For annotations: include context, assignee (if known), and ticket reference.
- Verify comments don't restate what code already says.
- Run the rubric check. Revise until it passes.
Degrees of freedom
Medium freedom
- Default: follow language-specific conventions exactly
- Allowed variation: verbosity may adapt to code complexity; internal vs. external APIs may have different detail levels
State awareness
Code documentation serves different reader states:
- First encounter: What does this do? Should I use it?
- Integration: What parameters? What's returned? What can go wrong?
- Debugging: Why was this implemented this way?
- Maintenance: What's the history? What should I not change?
- Refactoring: What depends on this? What's the contract?
References
