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.
When & Why to Use This Skill
The Global Commenting skill empowers Claude to write high-quality, minimal code documentation that focuses on 'why' rather than 'what'. By emphasizing evergreen comments and self-documenting code structures, it reduces technical debt and improves long-term maintainability across PHP, TypeScript, and JavaScript projects. It ensures that documentation remains relevant, professional, and strictly adheres to industry standards like PHPDoc and JSDoc.
Use Cases
- Explaining complex architectural decisions or non-obvious business logic that cannot be conveyed through code structure alone.
- Standardizing documentation using PHPDoc, JSDoc, or TSDoc to provide better IDE intellisense and team collaboration.
- Streamlining codebases during refactoring by identifying and removing redundant, obvious, or temporary comments that clutter the source.
- Improving code readability by replacing verbose comments with clear, self-explanatory naming conventions and clean code structures.
- Documenting complex data structures, such as specific array shapes in PHP or interface definitions in TypeScript, for better type safety and clarity.
| 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