Commenting Intent

What problem does it solve?

This Skill addresses the problem of redundant, unhelpful comments that merely restate obvious code, or the lack of comments explaining critical decisions. It ensures comments add real value by focusing on the "why" behind the code, non-obvious decisions, and complex logic, rather than its mechanical "what."

Core Features & Use Cases

• Focus on Rationale: Guides you to explain the reasoning behind design choices, algorithm selection, or specific values (e.g., magic numbers).
• Avoid Obvious Comments: Encourages deleting comments that simply restate self-evident code, promoting self-documenting code.
• Document Workarounds & Gotchas: Provides a clear place to explain unusual code necessitated by bugs or external constraints.
• Use Case: Instead of commenting total = a + b # Add a and b to get total, use this skill to explain MAX_RETRIES = 3 # Based on testing showing 3 retries handles 99.9% of transient failures.

Quick Start

Review the attached Python function. Identify any comments that merely restate obvious code. For any complex or non-obvious parts, add comments explaining the WHY behind the decision or logic.