global-commenting

编写自解释代码,使用最小化、永不过时的注释解释原因而非内容,避免临时的变更记录或明显的描述。在任何代码文件添加注释时使用此技能,确保注释通过解释复杂逻辑、业务规则或非显而易见的决策提供价值,而非描述代码的功能。在需要澄清的代码编写时应用此技能,在记录复杂算法或业务逻辑时,或在移除描述明显操作的过时或冗余注释时应用。此技能优先通过有意义命名和结构编写清晰、表达性强的代码,最小化对注释的需求,确保任何添加的注释都有帮助并解释意图或推理,避免留下关于最近更改、临时修复或属于提交消息或文档的信息的注释。

📖 中文导读:编写自解释代码,使用最小化、永不过时的注释解释原因而非内容,避免临时的变更记录或明显的描述。在任何代码文件添加注释时使用此技能,确保注释通过解释复杂逻辑、业务规则或非显而易见的决策提供价值,而非描述代码的功能。在需要澄清的代码编写时应用此技能,在记录复杂算法或业务逻辑时,或在移除描述明显操作的过时或冗余注释时应用。此技能优先通过有意义命名和结构编写清晰、表达性强的代码,最小化对注释的需求,确保任何添加的注释都有帮助并解释意图或推理,避免留下关于最近更改、临时修复或属于提交消息或文档的信息的注释。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Global Commenting description: Write self-documenting code with minimal, evergreen comments that explain WHY rather than WHAT, avoiding temporary change notes or obvious descriptions. Use this skill when adding comments to any code file to ensure comments provide value by explaining complex logic, business rules, or non-obvious decisions rather than describing what the code does. Apply this skill when writing code that needs clarification, when documenting complex algorithms or business logic, or when removing outdated or redundant comments that describe obvious operations. This skill prioritizes writing clear, expressive code through meaningful naming and structure that minimizes the need for comments, ensures any comments added are helpful and explain intent or reasoning, and avoids leaving comments about recent changes, temporary fixes, or information that belongs in commit messages or documentation.

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 code across the project (to determine if comments are needed)
  • When adding comments to explain complex algorithms, business logic, or non-obvious decisions
  • When documenting WHY code exists rather than WHAT it does
  • When refactoring code to make it more self-documenting and reduce comment needs
  • When removing outdated, redundant, or obvious comments
  • When identifying comments that describe recent changes or fixes (which should be removed)
  • When choosing meaningful variable and function names that reduce the need for explanatory comments
  • When cleaning up commented-out code blocks (which should be deleted, not kept as comments)
  • When ensuring comments remain evergreen and relevant long-term
  • When writing docstrings or JSDoc for public APIs, exported functions, or complex interfaces
  • When adding TODO or FIXME comments only when absolutely necessary with clear action items
  • When reviewing code to verify comments add value and aren't stating the obvious

Instructions

For details, refer to the information provided in this file: global commenting