# Comment Guidelines

> Code comment guidelines. Remove redundant comments, add strategic ones explaining WHY not WHAT. Applied automatically when modifying code.

- Skill: `majiayu000/comment-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/comment-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/comment-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/comment-guidelines

---


# Comment Guidelines

These guidelines should be automatically applied whenever writing or modifying code.

## Core Principles

1. **Self-documenting code first** - Use clear naming and structure; comments are last resort
2. **WHY over WHAT** - Comments explain intent and reasoning, not mechanics
3. **Reduce cognitive load** - Make non-obvious knowledge explicit
4. **Zero redundancy** - Never duplicate what code already expresses

## When to Add Comments

**DO comment:**
- Design decisions and trade-offs
- Non-obvious behavior or edge cases
- Interface contracts (public APIs, function signatures)
- Important context that isn't evident from code
- Gotchas and subtle behaviors
- Cross-module dependencies

**DON'T comment:**
- What the code literally does (self-evident)
- Well-named variables/functions
- Standard patterns and idioms
- Implementation details visible in code

## Application Rules

When modifying code:

1. **Remove** any comments that restate what code does
2. **Keep** comments that explain WHY something is done
3. **Add** comments only for non-obvious behavior or design decisions
4. **Update** existing comments if code changes make them stale
5. **Never** add comments just to fill space or appear thorough

## Examples

```typescript
// BAD: Restates the obvious
// Set user name to the input value
user.name = input.value;

// GOOD: Explains non-obvious behavior
// Normalize to lowercase for case-insensitive matching in search
user.searchKey = user.name.toLowerCase();

// BAD: Documents what is self-evident
// Loop through all items
for (const item of items) { ... }

// GOOD: Explains WHY this approach
// Process in reverse to allow safe removal during iteration
for (let i = items.length - 1; i >= 0; i--) { ... }
```

## Automatic Application

This skill does NOT need to be explicitly invoked. Claude should:
- Apply these principles whenever editing code
- Proactively clean up redundant comments encountered
- Add strategic comments only where they reduce cognitive load