Write and audit Python code comments using Antirez's nine-type taxonomy. Two modes — Write (add or improve comments in code) and Audit (classify and assess existing comments and produce a structured, prioritized report). Use when users request comment improvements, docstring additions, comment quality reviews, or documentation audits. Applies a systematic comment classification with Python-specific mapping (docstrings vs. inline # comments, type hints).
Two operational modes for Python code comments:
Core principle: comments explain why, code explains what. Type hints explain types.
Write mode triggers:
Audit mode triggers:
Nine comment types from antirez's "Writing system software: code comments". See references/taxonomy.md for full detail.
| Type | Name | Python Form | Purpose |
|------|------|-------------|---------|
| 1 | Function | Docstring | What the function/class/module does |
| 2 | Design | Docstring or # | Architecture rationale, API design choices |
| 3 | Why | Inline # | Non-obvious reasoning behind code |
| 4 | Teacher | Inline # | Domain knowledge, algorithm explanation |
| 5 | Checklist | Inline # | Steps that must not be skipped or reordered |
| 6 | Guide | # section headers | Navigation aids in long modules |
| Type | Name | Detection | Fix |
|------|------|-----------|-----|
| 7 | Trivial | Restates the code | Delete |
| 8 | Debt | TODO, FIXME, HACK | Resolve or create issue |
| 9 | Backup | Commented-out code | Delete (git preserves history) |
"""...""") - Types 1-2. Describe interface (what, args, returns, raises). Follow PEP 257.#) - Types 3-6. Describe implementation (why, how, context).# BAD: Comment duplicates type hint
def process(data: list[dict]) -> bool:
"""Process data.
Args:
data: A list of dictionaries # Redundant - type hint says this
"""
# GOOD: Docstring adds semantic meaning
def process(data: list[dict]) -> bool:
"""Process sensor readings and flag anomalies.
Args:
data: Sensor readings keyed by timestamp, each containing
'value', 'unit', and optional 'calibration_offset'
"""
"""Return the user's full name.""" (imperative mood, period)Execute in four phases.
Output: Inventory of existing documentation and code structure.
For each code element, determine what's missing:
Prioritize gaps by impact:
Output: Prioritized gap list with comment type needed for each.
Apply comments following these rules:
# for types 3-6references/docstring-styles.mdWriting rules per type:
references/docstring-styles.md# --- Section Name --- or # region/# endregionOutput: Commented code.
Output: Final commented code passing all checks.
Execute in four phases.
#, block #)Output: Comment inventory with locations.
For each comment, assign:
Quality criteria per type - see references/taxonomy.md for detail:
Output: Classified comment inventory with quality assessments.
Identify what's missing:
Severity levels:
Output: Gap analysis with severity ratings.
Generate structured audit report.
## Comment Audit Report
### Summary
- **Files analyzed:** N
- **Total comments:** N (docstrings: N, inline: N)
- **Comment density:** N comments per 100 LOC
- **Type distribution:** Type 1: N, Type 2: N, ... Type 9: N
- **Quality score:** N/10
### Critical Gaps
- [ ] {file}:{line} - {element} - Missing {type} comment - {impact}
### Issues Found
#### Negative Comments (fix or remove)
- {file}:{line} - Type {N} ({name}) - "{comment text}" - Action: {delete/resolve/rewrite}
#### Outdated Comments
- {file}:{line} - "{comment text}" - Mismatch: {description}
#### Quality Issues
- {file}:{line} - Type {N} - Issue: {description}
### Coverage Metrics
| Scope | With Docstring | Without | Coverage |
|-------|---------------|---------|----------|
| Modules | N | N | N% |
| Classes | N | N | N% |
| Public functions | N | N | N% |
| Public methods | N | N | N% |
### Recommendations
1. **Priority 1:** {action} - {N elements affected}
2. **Priority 2:** {action} - {N elements affected}
3. **Priority 3:** {action} - {N elements affected}
### Comment Style
- **Detected style:** {Google/NumPy/Sphinx/mixed}
- **Consistency:** {consistent/inconsistent}
- **Recommendation:** {standardize on X style}
See references/examples/audit-mode-examples.md for complete report examples.
x += 1, do not add # increment x"""Process data.""" on a complex function is worse than nothing__init__.py docstrings) follows type 1+2 patternsSearch for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer