Back to Details

comment-guidelines

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Comment Guidelines

注释指南

These guidelines should be automatically applied whenever writing or modifying code.
每当编写或修改代码时，都应自动遵循这些指南。

Core Principles

核心原则

  1. Self-documenting code first - Use clear naming and structure; comments are last resort
  2. WHY over WHAT - Comments explain intent and reasoning, not mechanics
  3. Reduce cognitive load - Make non-obvious knowledge explicit
  4. Zero redundancy - Never duplicate what code already expresses
  1. 优先使用自文档化代码 - 使用清晰的命名和结构；注释是最后的手段
  2. 解释原因而非内容 - 注释用于说明意图和推理，而非实现机制
  3. 降低认知负担 - 明确阐述非显而易见的知识
  4. 零冗余 - 绝不重复代码已表达的内容

When to Add Comments

何时添加注释

DO comment:
  • Design decisions and trade-offs
  • Non-obvious behavior or edge cases
  • Interface contracts (public APIs, function signatures)
  • Important context that isn't evident from code
  • Gotchas and subtle behaviors
  • Cross-module dependencies
DON'T comment:
  • What the code literally does (self-evident)
  • Well-named variables/functions
  • Standard patterns and idioms
  • Implementation details visible in code
应添加注释的场景：
  • 设计决策与权衡
  • 非显而易见的行为或边缘情况
  • 接口契约（公共API、函数签名）
  • 代码中无法体现的重要上下文
  • 容易出错的细节和微妙行为
  • 跨模块依赖
不应添加注释的场景：
  • 代码字面表达的内容（不言自明）
  • 命名清晰的变量/函数
  • 标准模式和惯用写法
  • 代码中可见的实现细节

Application Rules

应用规则

When modifying code:
  1. Remove any comments that restate what code does
  2. Keep comments that explain WHY something is done
  3. Add comments only for non-obvious behavior or design decisions
  4. Update existing comments if code changes make them stale
  5. Never add comments just to fill space or appear thorough
修改代码时：
  1. 移除任何重复代码内容的注释
  2. 保留解释实现原因的注释
  3. 仅在存在非显而易见的行为或设计决策时添加注释
  4. 更新因代码变更而过时的现有注释
  5. 切勿仅为填充空格或显得详尽而添加注释

Examples

示例

typescript
// BAD: Restates the obvious
// Set user name to the input value
user.name = input.value;

// GOOD: Explains non-obvious behavior
// Normalize to lowercase for case-insensitive matching in search
user.searchKey = user.name.toLowerCase();

// BAD: Documents what is self-evident
// Loop through all items
for (const item of items) { ... }

// GOOD: Explains WHY this approach
// Process in reverse to allow safe removal during iteration
for (let i = items.length - 1; i >= 0; i--) { ... }
typescript
// BAD: Restates the obvious
// Set user name to the input value
user.name = input.value;

// GOOD: Explains non-obvious behavior
// Normalize to lowercase for case-insensitive matching in search
user.searchKey = user.name.toLowerCase();

// BAD: Documents what is self-evident
// Loop through all items
for (const item of items) { ... }

// GOOD: Explains WHY this approach
// Process in reverse to allow safe removal during iteration
for (let i = items.length - 1; i >= 0; i--) { ... }

Automatic Application

自动应用

This skill does NOT need to be explicitly invoked. Claude should:
  • Apply these principles whenever editing code
  • Proactively clean up redundant comments encountered
  • Add strategic comments only where they reduce cognitive load
此技能无需显式调用。Claude应：
  • 在编辑代码时遵循这些原则
  • 主动清理遇到的冗余注释
  • 仅在能降低认知负担的地方添加关键注释