Global Commenting

---
name: global-commenting
description: Write self-documenting code with minimal, evergreen comments that explain complex logic without describing recent changes or temporary fixes. Use this skill when writing code comments, documentation strings, explaining complex algorithms, clarifying business logic, or deciding whether code needs comments. Apply when working with any source code files where comments or documentation might be added, ensuring comments remain relevant, helpful, and focused on explaining why rather than what the code does, while preferring clear code structure and naming over excessive commenting.
---

# Global Commenting

## When to use this skill

- When writing comments in any programming language
- When deciding whether code needs explanatory comments
- When documenting complex algorithms or business logic
- When explaining non-obvious code decisions or workarounds
- When writing docstrings or function documentation
- When refactoring code to make it more self-explanatory
- When reviewing existing comments for relevance and clarity
- When removing outdated or temporary comments
- When choosing between adding a comment vs improving code clarity
- When explaining why certain approaches were chosen
- When working with any source code files that may contain comments
- When documenting APIs, functions, or class interfaces
- When ensuring comments are evergreen and future-proof

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.

## Instructions

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