comments_skill

Overview

This skill teaches best practices for writing meaningful, minimal, and maintainable code comments. It focuses on when comments add value, how to document intent, and how to choose the right comment style for public APIs versus internal notes. The aim is clearer code, fewer stale comments, and improved team communication.

How this skill works

It inspects code context and guides developers to prefer self-explanatory names and minimal comments that explain the "why" rather than the "what." It recommends assessing necessity, renaming identifiers to clarify intent, and using different comment styles for public documentation versus internal notes. It also includes examples of poor and strong commenting patterns to illustrate recommended practices.

When to use it

• When complex business logic or algorithms cannot be made self-explanatory
• When documenting public APIs or library surfaces for consumers
• To clarify non-obvious workarounds, hacks, or side effects
• To warn about potential pitfalls or future refactoring needs
• When behavior depends on external constraints or domain knowledge

Best practices

• Assess necessity first—prefer code that explains itself through clear names and structure
• Document intent and business context; explain why a decision was made, not what the code does
• Use /// (or equivalent doc comments) for public API documentation and // for internal notes
• Avoid redundant comments that restate obvious code; remove deprecated or temporary blocks
• Keep comments concise, current, and actionable—update or delete them when code changes

Example use cases

• Documenting why a specific data structure is chosen for UI ordering
• Explaining suppression of a particular exception as an accepted state
• Marking a temporary workaround with a TODO and clear conditions for removal
• Adding API doc comments that list exceptions, side effects, and expected behavior
• Replacing verbose inline explanations by improving variable and method names