acaprino/python-comments

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

# 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 - Complex logic without why-comments, outdated comments
• Medium - Missing design rationale, missing guide comments
• Low - Missing private method docstrings, minor style inconsistencies

Output: Gap analysis with severity ratings.

Phase 4: Report

Generate structured audit report.

Audit Report Format

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

Key Constraints

• NEVER add trivial comments - If the code says x += 1, do not add # increment x
• NEVER add placeholder docstrings - """Process data.""" on a complex function is worse than nothing
• NEVER duplicate type hints - If type hints exist, document semantics not types
• NEVER change code logic - Comments and docstrings only, zero functional changes
• PRESERVE existing style - Match the project's existing docstring style
• PRESERVE valid comments - Only modify/delete comments that are negative types (7-9) or demonstrably wrong

Integration with Same-Package Skills

• python-refactor - Refactoring may require updating comments. Run write mode after refactoring to update docstrings
• python-tdd - Test docstrings benefit from type 1 (function) comments. Audit mode can assess test documentation
• python-performance-optimization - Performance-critical code benefits from type 4 (teacher) comments explaining algorithm choices
• python-packaging - Package-level documentation (__init__.py docstrings) follows type 1+2 patterns