global-commenting

Original source / Raw SKILL.md

---
name: Global Commenting
description: 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.
---

# 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)