global-commenting
Write self-documenting code with clear naming and structure, adding minimal, evergreen comments only when necessary to explain complex logic. Use this skill when writing or reviewing any code that might need comments. When refactoring code to make it more self-explanatory through better naming and structure. When deciding whether to add or remove comments from existing code. When ensuring comments explain why something is done rather than what is being done. When reviewing code to remove outdated or temporary change-related comments. This skill applies to all programming languages and all types of code files.
When & Why to Use This Skill
The Global Commenting skill optimizes code maintainability by enforcing self-documenting programming practices. It guides Claude to prioritize clear naming and structural clarity over redundant documentation, ensuring that comments are evergreen and focus on explaining the 'why' behind complex logic rather than the 'what'. This approach minimizes technical debt and enhances long-term readability across any programming language.
Use Cases
- Refactoring legacy code: Transforming obscure logic into self-explanatory code by improving variable naming and function structures.
- Automated Code Audits: Identifying and removing outdated, temporary, or change-related comments that no longer reflect the current state of the codebase.
- Logic Documentation: Adding precise, minimal comments to explain non-obvious business rules or complex architectural decisions that cannot be conveyed through code alone.
- Standardizing Documentation: Ensuring a consistent commenting style across multi-language projects to maintain high-quality, professional code standards.
| name | Global Commenting |
|---|---|
| description | Write self-documenting code with clear naming and structure, adding minimal, evergreen comments only when necessary to explain complex logic. Use this skill when writing or reviewing any code that might need comments. When refactoring code to make it more self-explanatory through better naming and structure. When deciding whether to add or remove comments from existing code. When ensuring comments explain why something is done rather than what is being done. When reviewing code to remove outdated or temporary change-related comments. This skill applies to all programming languages and all types of code files. |
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 writing any new code that might require comments or explanations
- When refactoring code to improve clarity through better naming and structure
- When deciding whether to add comments to complex logic or algorithms
- When removing outdated, temporary, or change-related comments from code
- When reviewing existing comments to ensure they remain relevant and evergreen
- When writing function or method documentation
- When explaining non-obvious business logic or architectural decisions
- When working with any code file in any programming language
- When ensuring code is self-documenting through clear variable and function names
- When avoiding comments that simply describe what the code does (prefer explaining why)
Instructions
For details, refer to the information provided in this file: global commenting