Python Comments

Purpose

Two operational modes for Python code comments:

• Write mode - Add missing comments, improve existing ones, fix negative-type comments

• 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

• Read entire file/module being commented

• Identify all existing comments and docstrings

• Map code structure: modules, classes, functions, complex blocks

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

• Module-level - Missing module docstring? Missing guide comments for sections?

• Class-level - Missing class docstring? Missing design rationale?

• Function-level - Missing docstring? Missing parameter semantics? Missing why-comments on complex logic?

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

• Choose correct type - Use taxonomy from Phase 2 classification

• Choose correct form - Docstring for types 1-2, inline # for types 3-6

• Choose correct style - Match project's existing docstring style; default to Google style. See references/docstring-styles.md

• Write concisely - Every word must earn its place

• 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

• No trivial comments added - Every comment adds information not in the code

• No type duplication - Docstrings don't repeat type hints

• Style consistency - All docstrings follow the same style (Google/NumPy/Sphinx)

• Existing comments preserved - Don't delete valid existing comments unless explicitly negative types

• 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

• Extract all comments and docstrings from target code

• Record location (file, line, scope)

• Record form (docstring, inline # , block # )

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

• Public API coverage - Percentage of public functions/classes/modules with docstrings

• Why-comment coverage - Complex logic blocks with non-obvious reasoning explained

• Design documentation - Architecture decisions documented at module/class level

• 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

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