rule-code-comments

Enforce WHY-first commenting and TSDoc guidance for TypeScript source files.

1|Updated Apr 17, 2025

Search Tags:#typescript #documentation #comments #coding-standards #self-documenting #domain-context

Ready to run

npx skills add https://github.com/carrot-foundation/schemas --skill rule-code-comments

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: rule-code-comments
Source: https://github.com/carrot-foundation/schemas/tree/main/.agents/skills/rule-code-comments
Command: npx skills add https://github.com/carrot-foundation/schemas --skill rule-code-comments

SYSTEM DOCUMENTATION & REQUIREMENTS

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.

Frequently Asked Questions about rule-code-comments

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write effective TypeScript comments that explain intent without cluttering the code?▼

Effective TypeScript comments prioritize self-documenting identifiers first, then add WHY-focused explanations for decisions and domain constraints. Apply TSDoc selectively to exported symbols to avoid over-commenting and clutter in your source files.

What is self-documenting code and when should I add comments in TypeScript?▼

Self-documenting code uses descriptive names for variables, functions, and types to convey intent without needing comments. Add comments only when necessary to explain WHY decisions were made or to document business rules and domain constraints.

How do I document domain context and business rules in TypeScript source files?▼

Document domain context in TypeScript by adding comments that justify decisions, explain trade-offs, and outline business constraints. This prevents ambiguity and guides future changes by clarifying the rationale behind specific code implementations.

When should I use TSDoc for exported symbols in a TypeScript project?▼

Use TSDoc selectively for exported symbols and metadata where it adds clear value. Avoid applying TSDoc everywhere to prevent clutter, focusing on public APIs and exported functions that benefit from structured metadata documentation.

What is the best way to refactor ambiguous TypeScript code for better maintainability?▼

The best way to refactor for maintainability is replacing ambiguous names with self-describing identifiers across your TypeScript codebase, then adding WHY-focused comments that document decisions, domain constraints, and governance rules.