# Write Clear Evergreen Code Comments

Teams often add comments that become stale or repeat obvious code. This skill guides AI assistants to write minimal comments that explain non-obvious decisions.

## Install

```bash
npx skillstore add devanb/global-commenting
```

## Metadata

- Status: approved
- Slug: devanb-global-commenting
- Skillstore revision: r1
- Version status: missing
- Tree hash: a36836da5074a4bbf65eacab02d0c41dfc2afb05b38d7bae8c227657d8a3ba44
- Author: DevanB
- GitHub username: DevanB
- License: MIT
- Repository: https://github.com/DevanB/lucidlog/tree/master/.claude/skills/global-commenting
- Ref: 0519034dad657fb1f7706e0550e962beeda73fdf
- 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: 79
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/devanb-global-commenting
- Manifest: https://skillstore.pages.dev/api/skills/devanb-global-commenting/manifest

## Capabilities

- Guides comments for PHP, TypeScript, JavaScript, and other code files.
- Supports PHPDoc blocks for PHP classes, methods, and functions.
- Supports JSDoc and TSDoc comments for TypeScript and JavaScript functions.
- Encourages comments that explain non-obvious business logic and algorithms.
- Helps review existing comments for relevance and long-term accuracy.
- Promotes clearer naming and structure before adding comments.

## Use Cases

- Improve Existing Code Comments: Review comments in a codebase and keep only those that explain lasting context.
- Standardize Docblocks: Create PHPDoc, JSDoc, or TSDoc comments that match a minimal commenting style.
- Reduce Comment Noise: Identify comments that repeat code behavior and suggest clearer naming or structure.

## Prompt Templates

### Add Essential Comments

```
Review this code and add only comments that explain non-obvious decisions. Avoid comments that repeat what the code already says.
```

### Write Docblocks

```
Add PHPDoc, JSDoc, or TSDoc comments where they help future maintainers. Keep each comment concise and focused on intent.
```

### Review Comment Quality

```
Review the existing comments in this change. Mark stale, redundant, or temporary comments, and suggest durable replacements only where needed.
```

### Refactor Before Commenting

```
Find places where clearer names or structure would remove the need for comments. Add comments only for business rules or algorithms that remain non-obvious.
```

## Limitations

- The packaged skill does not include the detailed external commenting standard.
- The linked standards file may be unavailable after marketplace installation.
- It provides writing guidance, not automated linting or enforcement.
- It does not replace project-specific documentation rules.

## Best Practices

- Explain why code exists when the reason is not clear from names and structure.
- Prefer clearer code before adding a comment.
- Keep comments durable by avoiding release dates, temporary notes, and recent-change history.

## Anti Patterns

- Do not comment every line or repeat obvious control flow.
- Do not preserve stale comments after logic changes.
- Do not use comments to hide unclear naming or overly complex structure.

## Security Audit

- Audited at: 2026-07-09T11:12:51.927\+00:00
- Summary: The static path traversal alert is a fixed Markdown link to a project standards document, not executable code or user-controlled file access. No prompt injection, data exfiltration, or malicious intent was found in SKILL.md.

## Stats

- Views: 204
- Downloads: 14
- Favorites: 1
- Popularity score: 0