AgentSkillsCN

Global Commenting

撰写富有意义的代码注释，着重解释“为什么”而非“是什么”，聚焦业务逻辑、非显而易见的解决方案、变通方法以及复杂算法，同时保持代码的自我文档化。在为代码添加注释以阐明设计初衷、记录复杂的业务逻辑、说明变通或临时解决方案、描述性能优化措施、编写函数文档（JSDoc、docstrings、XML文档），或审查代码以判断注释是否恰当时，可使用此技能。适用于处理任何包含需要解释逻辑的代码文件、公开API函数、复杂算法、安全关键代码，或架构层面的决策。此技能确保注释重点在于解释“为什么”而非“如何”（强调WHY而非WHAT），通过清晰的命名让代码具备自我文档化的能力（与其注释晦涩难懂的代码，不如重构使其更易理解），注释简洁且历久弥新（不再使用带有“谁”或“何时”的过时注释——Git会自动记录这些信息），为注释提供外部资源链接以补充背景信息，采用恰当的函数文档格式（TS/JS使用JSDoc，Python使用docstrings，.NET使用XML文档），在已提交的代码中不再出现TODO/FIXME（改用问题跟踪系统并引用对应的工单），同时及时删除已废弃的注释代码（Git历史仍会保留这些代码）。

SKILL.md
--- frontmatter
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