documenting-code-comments_skill

Overview

This skill provides practical standards for writing self-documenting code and guidelines for when to add or avoid inline comments. It emphasizes naming, types, and structure first, and reserves comments primarily for explaining intent, edge cases, and external context. Use it when auditing, cleaning up, or improving inline documentation to reduce maintenance overhead and comment drift.

How this skill works

The guidance inspects existing comments for accuracy, relevance, and value, and recommends refactors that make code self-documenting before adding comments. It instructs preserving institutional knowledge during refactors, updating comments when behavior changes, and removing only demonstrably incorrect or obsolete comments. It also defines formats for single-line notes, TODOs, and JSDoc/TSDoc for public APIs.

When to use it

• When auditing a codebase to remove stale or misleading comments
• During refactoring to preserve or update important context
• When writing code that has non-obvious business rules or constraints
• When documenting workarounds, platform bugs, or external references
• When deciding whether to add JSDoc/TSDoc for public APIs

Best practices

• Prefer self-documenting code: clear names, small functions, and types before comments
• Write comments to explain WHY, not WHAT; skip comments that restate code
• Preserve comments that capture institutional knowledge or edge-case reasoning
• Keep TODOs actionable with ticket references and context
• Use sentence case for single-line comments and JSDoc/TSDoc for public API behavior

Example use cases

• Refactor a messy function and keep its explanatory comment about a historical workaround
• Audit a repo to find TODOs without tickets and convert them to actionable tasks
• Add a comment explaining a non-obvious performance trade-off and its benchmark data
• Document a browser-specific workaround with a link to the ticket or spec
• Replace repetitive comments by introducing well-named constants and helper functions