playbooks

home / skills / oimiragieo / agent-studio / comment-usage

comment-usage skill

/.claude/skills/_archive/dead/comment-usage

This skill helps enforce meaningful, minimal comment usage by evaluating rationale, avoiding obvious notes, and documenting why complex behavior occurs.

npx playbooks add skill oimiragieo/agent-studio --skill comment-usage

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.7 KB
---
name: comment-usage
description: This rule dictates how comments should be used within the codebase to enhance understanding and avoid clutter.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/*.*'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Comment Usage Skill

<identity>
You are a coding standards expert specializing in comment usage.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Use comments sparingly, and when you do, make them meaningful.
- Don't comment on obvious things. Excessive or unclear comments can clutter the codebase and become outdated.
- Use comments to convey the "why" behind specific actions or explain unusual behavior and potential pitfalls.
- Provide meaningful information about the function's behavior and explain unusual behavior and potential pitfalls.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for comment usage compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill enforces pragmatic comment usage in JavaScript code to improve clarity without adding clutter. It helps teams keep comments meaningful, current, and focused on intent rather than restating code. The goal is clearer maintainability and fewer stale or misleading annotations.

How this skill works

The skill analyzes JavaScript source to detect unnecessary, redundant, or missing comments and flags comments that repeat obvious code. It highlights places where comments should explain intent, trade-offs, workarounds, or nonobvious behavior, and suggests rewriting or removing vague or out-of-date comments. It can also propose succinct comment templates for function intent and unusual edge cases.

When to use it

  • During code reviews to validate comment quality and relevance
  • When refactoring to remove outdated or redundant comments
  • When documenting complex business logic or nonobvious algorithms
  • Before merging PRs to ensure comments explain intent and assumptions
  • When onboarding new team members to set a consistent commenting style

Best practices

  • Comment sparingly: prefer self-explanatory code and use comments for intent, rationale, and limitations only.
  • Avoid restating code: do not write comments that simply repeat variable names or operations.
  • Explain the why: document reasons for decisions, trade-offs, and known edge cases or hacks.
  • Keep comments accurate and short; update or remove comments that become misleading.
  • Use comments to document public API behavior, input/output expectations, and side effects.
  • Prefer TODOs with context and a clear owner or timestamp when adding temporary notes.

Example use cases

  • Review a pull request and remove comments that duplicate code while adding explanation for a complex algorithm.
  • Refactor legacy code by converting verbose inline comments into concise explanations of intent and known pitfalls.
  • Add comment blocks for public functions describing inputs, outputs, side effects, and failure modes.
  • Identify and flag comments that reference removed code, outdated assumptions, or irrelevant history.
  • Suggest improvement for a confusing workaround by explaining why it exists and linking to an issue or test.

FAQ

When should I use comments instead of renaming code or refactoring?

Prefer refactoring or clearer names first; use comments when behavior, trade-offs, or historical context cannot be captured by code alone.

How do I avoid comments becoming stale?

Keep comments minimal and test-backed, require comment updates in the same PR that changes behavior, and reference related tests or issues for context.