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