code-comment-standards

Enforce current TSDoc comments and @see links in TypeScript code.

Updated May 8, 2025
One-click install
npx skills add https://github.com/mbelenmontoya/design-token-manager-api --skill code-comment-standards
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: code-comment-standards
Source: https://github.com/mbelenmontoya/design-token-manager-api/tree/main/.claude/skills/code-comment-standards
Command: npx skills add https://github.com/mbelenmontoya/design-token-manager-api --skill code-comment-standards

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Enforces current, clear, and maintainable code comments across a codebase to reduce misunderstandings and technical debt.

Core Features & Use Cases

  • Enforces removal of stale phase/task/step references and encourages documentation-driven context.
  • Promotes the use of TSDoc for public APIs and explicit @see links to architecture/docs.
  • Ideal for development, code reviews, and pre-commit checks to sustain consistent commenting practices.

Quick Start

Apply the code-comment-standards to a TypeScript file to ensure current behavior is described, public APIs are documented with TSDoc, and references to plans/docs are properly linked.

Frequently Asked Questions about code-comment-standards

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

FAQPage Schema
How do I enforce TSDoc standards for public API comments in TypeScript?

You can enforce TSDoc standards by applying comment validation during development and pre-commit checks to ensure public APIs include required @param and @returns tags. This validates that public API comments are fully documented with TSDoc syntax.

What is the best way to remove stale phase references from code comments?

The best way to remove stale phase references is to use a linting rule that detects outdated task or step mentions in comments and flags them for removal. This enforces the elimination of stale phase references, ensuring comments describe current functionality accurately.

Can I use code comment standards during pre-commit checks?

Yes, you can use code comment standards during pre-commit checks to sustain consistent commenting practices. It is designed for software projects using TypeScript and JavaScript to validate comments before code is committed.

How do I require actionable context in TODO comments?

You can require actionable context in TODO comments by enforcing a validation rule that checks for descriptive details or explicit links. This ensures TODOs include actionable context or links to documentation, preventing vague task notes.

How do I link architecture details in code comments using TSDoc?

You link architecture details by enforcing the use of the @see tag within TSDoc comments to reference external documentation. This requires documentation links via @see for architecture details, ensuring developers can easily navigate to relevant architectural docs.

Does this code comment linter work with JavaScript or only TypeScript?

This code comment linter works with both JavaScript and TypeScript. It is designed for software projects using TypeScript and JavaScript during development, code reviews, and pre-commit checks to maintain high-quality, current code comments.