rule-code-comments

What problem does it solve?

This Skill provides guidelines to write effective comments that clarify intent, rationale, and constraints, promoting self-documenting code and better maintainability.

Core Features & Use Cases

• Self-documenting code first: rename variables, functions, and types to convey intent and reduce the need for extraneous comments.
• Explain WHY, not WHAT: when a comment is necessary, justify decisions and link domain context or methodology decisions.
• Domain context and governance: document business rules, constraints, and trade-offs to prevent ambiguity and guide future changes.
• TSDoc guidance: apply TSDoc selectively for exported symbols and metadata, avoiding over-commenting and clutter.

Quick Start

Review your TypeScript codebase and replace ambiguous names with self-describing identifiers, then add WHY-focused comments that document decisions and domain constraints.