global-commenting
编写有意义的代码注释,解释原因而非事实,关注业务逻辑、不明显解决方案、权宜之计和复杂算法,同时保持代码自文档化。在添加注释解释原因、记录复杂的业务逻辑、解释权宜之计或临时解决方案、描述性能优化、编写函数文档(JSDoc、docstrings、XML docs)或审查代码以进行适当的注释时使用此技能。在处理包含需要解释的逻辑的任何代码文件、公共 API 函数、复杂算法、安全关键代码或架构决策时使用。此技能确保注释解释原因而非实现(WHY 而非 WHAT),通过清晰的命名(重构不清晰的代码而非注释)实现自文档化代码,简洁且永不过时的注释(无谁/何时过时的注释 - Git 跟踪此信息),链接到外部资源以提供上下文,正确的函数文档格式(TS/JS 的 JSDoc,Python 的 docstrings,XML d
📖 中文导读:编写有意义的代码注释,解释原因而非事实,关注业务逻辑、不明显解决方案、权宜之计和复杂算法,同时保持代码自文档化。在添加注释解释原因、记录复杂的业务逻辑、解释权宜之计或临时解决方案、描述性能优化、编写函数文档(JSDoc、docstrings、XML docs)或审查代码以进行适当的注释时使用此技能。在处理包含需要解释的逻辑的任何代码文件、公共 API 函数、复杂算法、安全关键代码或架构决策时使用。此技能确保注释解释原因而非实现(WHY 而非 WHAT),通过清晰的命名(重构不清晰的代码而非注释)实现自文档化代码,简洁且永不过时的注释(无谁/何时过时的注释 - Git 跟踪此信息),链接到外部资源以提供上下文,正确的函数文档格式(TS/JS 的 JSDoc,Python 的 docstrings,XML d 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: Global Commenting description: Write meaningful code comments that explain WHY rather than WHAT, focusing on business logic, non-obvious solutions, workarounds, and complex algorithms while keeping code self-documenting. Use this skill when adding comments to explain rationale, documenting complex business logic, explaining workarounds or temporary solutions, describing performance optimizations, writing function documentation (JSDoc, docstrings, XML docs), or reviewing code for appropriate commenting. Apply when working on any code file that contains logic requiring explanation, public API functions, complex algorithms, security-critical code, or architectural decisions. This skill ensures comments explain rationale not implementation (WHY not WHAT), self-documenting code through clear naming (refactor unclear code instead of commenting), concise and evergreen comments (no who/when dated comments - Git tracks this), links to external resources for context, proper function documentation format (JSDoc for TS/JS, docstrings for Python, XML docs for .NET), no TODO/FIXME in committed code (use issue tracking system instead and reference ticket), and deletion of dead commented-out code (Git history preserves it).
Global Commenting
When to use this skill:
- When explaining business logic or domain-specific rules with ticket references
- When documenting non-obvious implementation decisions
- When describing workarounds for browser bugs or library limitations with bug report links
- When explaining performance optimizations and their trade-offs with profiling data links
- When documenting complex algorithms or calculations with Wikipedia/paper links
- When noting security considerations or sensitive operations (OWASP recommendations)
- When explaining data flow or architectural patterns (e.g., function called from multiple places)
- When writing JSDoc comments for TypeScript/JavaScript public API functions
- When writing docstrings for Python public functions (Google style)
- When writing XML documentation for .NET public methods
- When documenting public API functions or library interfaces
- When reviewing code to determine if comments should be added or removed
- When deciding whether to comment or refactor unclear code (prefer refactoring)
- When replacing TODO/FIXME with issue tracker references
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