python-comments

What this skill does

# Python Comments

## Purpose

Two operational modes for Python code comments:

1. **Write mode** - Add missing comments, improve existing ones, fix negative-type comments
2. **Audit mode** - Classify all comments, identify gaps, produce structured quality report

Core principle: comments explain *why*, code explains *what*. Type hints explain *types*.

## When to Invoke

**Write mode triggers:**
- User requests "add comments", "document this", "improve comments"
- Code review flags missing docstrings or unclear logic
- New module/class/function lacks documentation
- Complex algorithm or business rule needs explanation

**Audit mode triggers:**
- User requests "review comments", "comment quality", "documentation audit"
- Pre-release documentation review
- Onboarding prep for new team members
- Legacy code assessment

## When NOT to Invoke

- Code is scheduled for deletion
- User wants API reference generation (use documentation tools instead)
- User wants type stub generation (use type hint tools instead)
- Trivial scripts or one-off scripts where comments add no value

## Antirez Comment Taxonomy for Python

Nine comment types from antirez's "Writing system software: code comments". See `references/taxonomy.md` for full detail.

### Positive Types (write these)

| 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 |

### Negative Types (detect and fix these)

| 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) |

## Python-Specific Mapping

### Docstrings vs Inline Comments

- **Docstrings** (`"""..."""`) - Types 1-2. Describe *interface* (what, args, returns, raises). Follow PEP 257.
- **Inline comments** (`#`) - Types 3-6. Describe *implementation* (why, how, context).
- **Type hints** - Reduce comment burden. Document *semantics* in docstrings, not types.

### Type Hints Reduce Comment Burden

```python
# 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'
    """
```

### PEP 257 Essentials

- One-line docstrings: `"""Return the user's full name."""` (imperative mood, period)
- Multi-line: summary line, blank line, elaboration
- All public modules, classes, functions, methods need docstrings
- Private methods: docstring if logic is non-obvious

## Write Mode Workflow

Execute in four phases.

### Phase 1: Scan

1. Read entire file/module being commented
2. Identify all existing comments and docstrings
3. Map code structure: modules, classes, functions, complex blocks
4. Note type hints already present (reduces docstring burden)

**Output:** Inventory of existing documentation and code structure.

### Phase 2: Classify Gaps

For each code element, determine what's missing:

1. **Module-level** - Missing module docstring? Missing guide comments for sections?
2. **Class-level** - Missing class docstring? Missing design rationale?
3. **Function-level** - Missing docstring? Missing parameter semantics? Missing why-comments on complex logic?
4. **Block-level** - Complex algorithms without teacher comments? Non-obvious conditions without why-comments? Multi-step processes without checklist comments?

Prioritize gaps by impact:
- **Critical** - Public API without docstring, complex algorithm without explanation
- **High** - Non-obvious business rule without why-comment, multi-step process without checklist
- **Medium** - Missing guide comments in long modules, missing design rationale
- **Low** - Private helpers without docstrings (skip if logic is obvious)

**Output:** Prioritized gap list with comment type needed for each.

### Phase 3: Write

Apply comments following these rules:

1. **Choose correct type** - Use taxonomy from Phase 2 classification
2. **Choose correct form** - Docstring for types 1-2, inline `#` for types 3-6
3. **Choose correct style** - Match project's existing docstring style; default to Google style. See `references/docstring-styles.md`
4. **Write concisely** - Every word must earn its place
5. **Fix negatives** - Delete trivial comments (type 7), resolve or issue-track debt (type 8), delete backup code (type 9)

Writing rules per type:
- **Type 1 (Function):** Imperative mood. Document purpose, args semantics (not types if hints exist), returns, raises, side effects. See `references/docstring-styles.md`
- **Type 2 (Design):** Explain *why this approach* over alternatives. Place at module/class level or above complex function
- **Type 3 (Why):** One line above the non-obvious code. Start with "why" reasoning, not "what" description
- **Type 4 (Teacher):** Explain domain concept or algorithm. Link to external reference if applicable
- **Type 5 (Checklist):** Number the steps. Mark order-dependent sequences. Note what breaks if skipped
- **Type 6 (Guide):** Section headers in long modules. Use `# --- Section Name ---` or `# region`/`# endregion`

**Output:** Commented code.

### Phase 4: Verify

1. **No trivial comments added** - Every comment adds information not in the code
2. **No type duplication** - Docstrings don't repeat type hints
3. **Style consistency** - All docstrings follow the same style (Google/NumPy/Sphinx)
4. **Existing comments preserved** - Don't delete valid existing comments unless explicitly negative types
5. **Code unchanged** - Only comments/docstrings modified, zero logic changes

**Output:** Final commented code passing all checks.

## Audit Mode Workflow

Execute in four phases.

### Phase 1: Collect

1. Extract all comments and docstrings from target code
2. Record location (file, line, scope)
3. Record form (docstring, inline `#`, block `#`)
4. Record associated code element (module, class, function, block)

**Output:** Comment inventory with locations.

### Phase 2: Classify

For each comment, assign:
- **Type** (1-9 from taxonomy)
- **Quality** (good / adequate / poor)
- **Accuracy** (correct / outdated / misleading)

Quality criteria per type - see `references/taxonomy.md` for detail:
- Type 1 (Function): Covers purpose, args, returns, raises? Imperative mood?
- Type 2 (Design): Explains rationale? References alternatives considered?
- Type 3 (Why): Explains reasoning, not just restates code?
- Type 4 (Teacher): Accurate domain explanation? Links to sources?
- Type 5 (Checklist): Steps numbered? Consequences of skipping noted?
- Type 6 (Guide): Consistent format? Matches actual code sections?
- Type 7 (Trivial): Delete candidate
- Type 8 (Debt): Has actionable resolution path?
- Type 9 (Backup): Delete candidate

**Output:** Classified comment inventory with quality assessments.

### Phase 3: Gap Analysis

Identify what's missing:
1. **Public API coverage** - Percentage of public functions/classes/modules with docstrings
2. **Why-comment coverage** - Complex logic blocks with non-obvious reasoning explained
3. **Design documentation** - Architecture decisions documented at module/class level
4. **Negative type count** - Number of trivial, debt, and backup comments

Severity levels:
- **Critical** - Public API without docstrings, misleading comments
- **High** - Comple