skills.rest
carrot-foundation
carrot-foundationOFFICIAL
Explore all skills by this author →
WebsiteGitHub

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
One-click install
npx skills add https://github.com/carrot-foundation/schemas --skill rule-code-comments
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
cjdutoitcjdutoit
3

the-standard-code-csharp

Validate C# source code for style rules, naming conventions, and comment formatting.

Community
Basic
webdriveriowebdriverio
11

Global Commenting

Enforce global comment style and coverage standards in Claude Code projects.

Official
Basic
XiaoPuOuOXiaoPuOuO
1

coding-standards

Enforce universal coding standards across TypeScript and JavaScript projects.

Community
Advanced
patricio0312revpatricio0312rev
5

jsdoc-typescript-docs

Generate API documentation from JSDoc comments in TypeScript projects.

Community
Intermediate