# Global Commenting

> Write minimal, evergreen code comments that explain complex logic without documenting obvious behavior or temporary changes. Use this skill when adding comments to PHP files, TypeScript/JavaScript files, or any code files, when documenting complex algorithms or business logic, when adding PHPDoc blocks or JSDoc comments, when writing self-documenting code with clear naming, or when reviewing existing comments for relevance and necessity. Focus on keeping code self-explanatory through clear structure and naming rather than relying heavily on comments.

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

---


# Global Commenting

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle global commenting.

## When to use this skill

- When adding comments to PHP, TypeScript, JavaScript, or any code files
- When documenting complex business logic or algorithms that aren't immediately obvious
- When writing PHPDoc blocks for PHP classes, methods, or functions
- When adding JSDoc or TSDoc comments for TypeScript/JavaScript functions
- When explaining the "why" behind non-obvious code decisions
- When refactoring code to be more self-documenting and reduce comment necessity
- When reviewing existing comments to ensure they're evergreen and still relevant
- When removing outdated comments about temporary fixes or recent changes
- When documenting complex array shapes or data structures in PHPDoc
- When choosing between adding a comment vs. refactoring for clarity

## Instructions

For details, refer to the information provided in this file:
[global commenting](../../../agent-os/standards/global/commenting.md)