# Write Clear Code Comments

Poor comments become stale and hide important design intent. This skill helps Claude, Codex, and Claude Code write concise comments that explain non-obvious logic.

## Install

```bash
npx skillstore add eis-its/global-commenting
```

## Metadata

- Status: approved
- Slug: eis-its-global-commenting
- Skillstore revision: r1
- Version status: missing
- Tree hash: 1bb48f28f748ccc8cdfb855b42a1c7ebaa8111d983a83b58bd24c409c71b4a13
- Author: EIS-ITS
- GitHub username: EIS-ITS
- License: MIT
- Repository: https://github.com/EIS-ITS/vss-cli/tree/main/.claude/skills/global-commenting
- Ref: 26421118b848d9f1efc0aa169d8a7a9e7e0a877e
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: filesystem
- Quality score: 78
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/eis-its-global-commenting
- Manifest: https://skillstore.pages.dev/api/skills/eis-its-global-commenting/manifest

## Capabilities

- Guides when to add comments versus improving code names or structure.
- Encourages comments that explain intent, tradeoffs, and complex logic.
- Supports docstrings, function documentation, API notes, and class interface comments.
- Helps review and remove outdated, temporary, or change-history comments.
- Applies commenting guidance across programming languages and source files.

## Use Cases

- Document Complex Logic: Add concise comments for algorithms, business rules, and non-obvious tradeoffs.
- Refine Existing Comments: Review comments during maintenance and replace stale notes with durable explanations.
- Review Pull Requests: Check whether added comments explain intent without duplicating readable code.

## Prompt Templates

### Decide If Comments Are Needed

```
Review this file and identify where comments would add durable context. Prefer better names or structure when a comment is unnecessary.
```

### Improve Existing Comments

```
Review the existing comments in this change. Rewrite comments that are stale, temporary, or focused on recent edits.
```

### Document Business Logic

```
Add comments for the non-obvious business rules in this module. Explain intent, constraints, and tradeoffs without restating each line.
```

### Set Commenting Standard

```
Audit this component for comment quality across functions, classes, and APIs. Propose a concise commenting approach for future changes.
```

## Limitations

- Does not include language-specific style guides or generated examples.
- Depends on the assistant seeing the relevant code context.
- Does not validate comment accuracy against runtime behavior.
- References an external parent-directory standards file that may not be packaged with the skill.

## Best Practices

- Use comments to explain intent, constraints, and tradeoffs that code cannot show clearly.
- Improve names, structure, and tests before adding comments that restate obvious behavior.
- Keep comments durable by avoiding dates, ticket history, and temporary implementation notes.

## Anti Patterns

- Adding comments that narrate each line of straightforward code.
- Leaving comments that describe old behavior, recent fixes, or temporary workarounds.
- Using comments to compensate for unclear names or avoidable complexity.

## Security Audit

- Audited at: 2026-07-09T14:19:27.59\+00:00
- Summary: The static filesystem finding is confirmed because SKILL.md references a parent-directory standards file outside the skill folder. No evidence of prompt injection or other semantic abuse was found in the scanned file, but the external reference makes the effective instructions unaudited.

## Stats

- Views: 216
- Downloads: 14
- Favorites: 0
- Popularity score: 0