Code Documentation & Self-Explanatory Code

代码文档与自解释代码

Auto-activate when: User discusses comments, documentation, docstrings, code clarity, code quality, API docs, JSDoc, Python docstrings, or asks about commenting strategies.

自动激活场景： 用户讨论注释、文档、文档字符串、代码清晰度、代码质量、API文档、JSDoc、Python文档字符串，或询问注释策略时。

Core Principle

核心原则

Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.

Most code does not need comments. Well-written code with clear naming and structure is self-documenting.

The best comment is the one you don't need to write because the code is already obvious.

编写能自我说明的代码。仅在必要时添加注释，解释‘为什么’而非‘是什么’。

大多数代码不需要注释。命名清晰、结构良好的代码本身就是自文档化的。

最好的注释是你无需编写的注释，因为代码本身已经一目了然。

The Commenting Philosophy

注释理念

When to Comment

何时添加注释

✅ DO comment when explaining:

WHY something is done (business logic, design decisions)
Complex algorithms and their reasoning
Non-obvious trade-offs or constraints
Workarounds for bugs or limitations
API contracts and public interfaces
Regex patterns and what they match
Performance considerations or optimizations
Constants and magic numbers
Gotchas or surprising behaviors

❌ DON'T comment when:

The code is obvious and self-explanatory
The comment repeats the code (redundant)
Better naming would eliminate the need
The comment would become outdated quickly
It's decorative or organizational noise
It states what a standard language construct does

✅ 建议添加注释的场景：

为什么要这么做（业务逻辑、设计决策）
复杂算法及其设计思路
非显而易见的取舍或约束条件
针对Bug或限制的临时解决方案
API契约与公共接口
正则表达式及其匹配规则
性能考量或优化措施
常量与魔术数字
容易踩坑的特殊行为

❌ 不建议添加注释的场景：

代码本身一目了然、可自我说明
注释重复了代码的内容（冗余）
可以通过更优命名来替代注释
注释会很快过时
装饰性或组织性的无意义注释
解释标准语言结构的功能

Comment Anti-Patterns

注释反模式

❌ 1. Obvious Comments

❌ 1. 显而易见的注释

BAD:

python

counter = 0  # Initialize counter to zero
counter += 1  # Increment counter by one
user_name = input("Enter name: ")  # Get user name from input

Better: No comment needed - the code is self-explanatory.

反面示例：

python

counter = 0  # Initialize counter to zero
counter += 1  # Increment counter by one
user_name = input("Enter name: ")  # Get user name from input

更好的写法： 无需添加注释——代码本身已能自我说明。

❌ 2. Redundant Comments

❌ 2. 冗余注释

BAD:

python

def get_user_name(user):
    return user.name  # Return the user's name

def calculate_total(items):
    # Loop through items and sum the prices
    total = 0
    for item in items:
        total += item.price
    return total

Better:

python

def get_user_name(user):
    return user.name

def calculate_total(items):
    return sum(item.price for item in items)

反面示例：

python

def get_user_name(user):
    return user.name  # Return the user's name

def calculate_total(items):
    # Loop through items and sum the prices
    total = 0
    for item in items:
        total += item.price
    return total

更好的写法：

python

def get_user_name(user):
    return user.name

def calculate_total(items):
    return sum(item.price for item in items)

❌ 3. Outdated Comments

❌ 3. 过时注释

BAD:

python

undefined

反面示例：

python

undefined

Calculate tax at 5% rate

tax = price * 0.08 # Actually 8%, comment is wrong

DEPRECATED: Use new_api_function() instead

def old_function(): # Still being used, comment is misleading pass


**Better:** Keep comments in sync with code, or remove them entirely.

---

def old_function(): # Still being used, comment is misleading pass


**更好的写法：** 保持注释与代码同步，或直接删除注释。

---

❌ 4. Noise Comments

❌ 4. 无意义注释

BAD:

python

undefined

反面示例：

python

undefined

Start of function

def calculate(): # Declare variable result = 0 # Return result return result

End of function


**Better:** Remove all of these comments.

---


**更好的写法：** 删除所有此类注释。

---

❌ 5. Dead Code & Changelog Comments

❌ 5. 死代码与变更日志注释

BAD:

python

undefined

反面示例：

python

undefined

Don't comment out code - use version control

def old_function():

return "deprecated"

Don't maintain history in comments

Modified by John on 2023-01-15

Fixed bug reported by Sarah on 2023-02-03


**Better:** Delete the code. Git has the history.

---


**更好的写法：** 删除代码。Git会保留历史记录。

---

Good Comment Examples

优秀注释示例

✅ Complex Business Logic

✅ 复杂业务逻辑

python

undefined

python

undefined

Apply progressive tax brackets: 10% up to $10k, 20% above

This matches IRS publication 501 for 2024

def calculate_progressive_tax(income): if income <= 10000: return income * 0.10 else: return 1000 + (income - 10000) * 0.20

undefined

def calculate_progressive_tax(income): if income <= 10000: return income * 0.10 else: return 1000 + (income - 10000) * 0.20

undefined

✅ Non-obvious Algorithms

✅ 非显而易见的算法

python

undefined

python

undefined

Using Floyd-Warshall for all-pairs shortest paths

because we need distances between all nodes.

Time: O(n³), Space: O(n²)

for k in range(vertices): for i in range(vertices): for j in range(vertices): dist[i][j] = min(dist[i][j], dist[i][k] + dist[k][j])

undefined

for k in range(vertices): for i in range(vertices): for j in range(vertices): dist[i][j] = min(dist[i][j], dist[i][k] + dist[k][j])

undefined

✅ Regex Patterns

✅ 正则表达式

python

undefined

python

undefined

Match email format: username@domain.extension

Allows letters, numbers, dots, hyphens in username

Requires valid domain and 2+ char extension

email_pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$'

undefined

email_pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$'

undefined

✅ API Constraints or Gotchas

✅ API约束或注意事项

python

undefined

python

undefined

GitHub API rate limit: 5000 requests/hour for authenticated users

We implement exponential backoff to handle rate limiting

await rate_limiter.wait() response = await fetch(github_api_url)

undefined

await rate_limiter.wait() response = await fetch(github_api_url)

undefined

✅ Workarounds for Bugs

✅ Bug临时解决方案

python

undefined

python

undefined

HACK: Workaround for bug in library v2.1.0

Remove after upgrading to v2.2.0

See: https://github.com/library/issues/123

if library_version == "2.1.0": apply_workaround()

---

if library_version == "2.1.0": apply_workaround()

---

Decision Framework

决策框架

Before writing a comment, ask yourself:

在编写注释前，先问自己以下问题：

Step 1: Is the code self-explanatory?

步骤1：代码是否能自我说明？

If YES → No comment needed
If NO → Continue to step 2

如果是 → 无需添加注释
如果否 → 进入步骤2

Step 2: Would a better variable/function name eliminate the need?

步骤2：更优的变量/函数命名能否替代注释？

If YES → Refactor the code instead
If NO → Continue to step 3

如果是 → 重构代码而非添加注释
如果否 → 进入步骤3

Step 3: Does this explain WHY, not WHAT?

步骤3：注释是解释‘为什么’而非‘是什么’吗？

If explaining WHAT → Refactor code to be clearer
If explaining WHY → Good comment candidate

如果是解释‘是什么’ → 重构代码使其更清晰
如果是解释‘为什么’ → 适合添加注释

Step 4: Will this help future maintainers?

步骤4：注释对未来的维护者有帮助吗？

If YES → Write the comment
If NO → Skip it

如果是 → 编写注释
如果否 → 跳过

Special Cases for Comments

注释的特殊场景

Public APIs and Docstrings

公共API与文档字符串

Python Docstrings

Python文档字符串

python

def calculate_compound_interest(
    principal: float,
    rate: float,
    time: int,
    compound_frequency: int = 1
) -> float:
    """
    Calculate compound interest using the standard formula.

    Args:
        principal: Initial amount invested
        rate: Annual interest rate as decimal (e.g., 0.05 for 5%)
        time: Time period in years
        compound_frequency: Times per year interest compounds (default: 1)

    Returns:
        Final amount after compound interest

    Raises:
        ValueError: If any parameter is negative

    Example:
        >>> calculate_compound_interest(1000, 0.05, 10)
        1628.89
    """
    if principal < 0 or rate < 0 or time < 0:
        raise ValueError("Parameters must be non-negative")

    # Compound interest formula: A = P(1 + r/n)^(nt)
    return principal * (1 + rate / compound_frequency) ** (compound_frequency * time)

python

def calculate_compound_interest(
    principal: float,
    rate: float,
    time: int,
    compound_frequency: int = 1
) -> float:
    """
    Calculate compound interest using the standard formula.

    Args:
        principal: Initial amount invested
        rate: Annual interest rate as decimal (e.g., 0.05 for 5%)
        time: Time period in years
        compound_frequency: Times per year interest compounds (default: 1)

    Returns:
        Final amount after compound interest

    Raises:
        ValueError: If any parameter is negative

    Example:
        >>> calculate_compound_interest(1000, 0.05, 10)
        1628.89
    """
    if principal < 0 or rate < 0 or time < 0:
        raise ValueError("Parameters must be non-negative")

    # Compound interest formula: A = P(1 + r/n)^(nt)
    return principal * (1 + rate / compound_frequency) ** (compound_frequency * time)

JavaScript/TypeScript JSDoc

javascript

/**
 * Fetch user data from the API.
 *
 * @param {string} userId - The unique user identifier
 * @param {Object} options - Configuration options
 * @param {boolean} options.includeProfile - Include profile data (default: true)
 * @param {number} options.timeout - Request timeout in ms (default: 5000)
 *
 * @returns {Promise<User>} User object with requested fields
 *
 * @throws {Error} If userId is invalid or request fails
 *
 * @example
 * const user = await fetchUser('123', { includeProfile: true });
 */
async function fetchUser(userId, options = {}) {
  // Implementation
}

javascript

/**
 * Fetch user data from the API.
 *
 * @param {string} userId - The unique user identifier
 * @param {Object} options - Configuration options
 * @param {boolean} options.includeProfile - Include profile data (default: true)
 * @param {number} options.timeout - Request timeout in ms (default: 5000)
 *
 * @returns {Promise<User>} User object with requested fields
 *
 * @throws {Error} If userId is invalid or request fails
 *
 * @example
 * const user = await fetchUser('123', { includeProfile: true });
 */
async function fetchUser(userId, options = {}) {
  // Implementation
}

Constants and Configuration

常量与配置

python

undefined

python

undefined

Based on network reliability studies (95th percentile)

MAX_RETRIES = 3

AWS Lambda timeout is 15s, leaving 5s buffer for cleanup

API_TIMEOUT = 10000 # milliseconds

Cache duration optimized for balance between freshness and load

See: docs/performance-tuning.md

CACHE_TTL = 300 # 5 minutes

---

CACHE_TTL = 300 # 5 minutes

---

Annotations for TODOs and Warnings

TODO与警告类注释

python

undefined

python

undefined

TODO: Replace with proper authentication after security review

Issue: #456

def temporary_auth(user): return True

WARNING: This function modifies the original array instead of creating a copy

def sort_in_place(arr): arr.sort() return arr

FIXME: Memory leak in production - investigate connection pooling

Ticket: JIRA-789

def get_connection(): return create_connection()

PERF: Consider caching this result if called frequently in hot path

def expensive_calculation(data): return complex_algorithm(data)

SECURITY: Validate input to prevent SQL injection before using in query

def build_query(user_input): sanitized = escape_sql(user_input) return f"SELECT * FROM users WHERE name = '{sanitized}'"

undefined

def build_query(user_input): sanitized = escape_sql(user_input) return f"SELECT * FROM users WHERE name = '{sanitized}'"

undefined

Common Annotation Keywords

常见注释关键字

```
TODO:
```
- Work that needs to be done
```
FIXME:
```
- Known bugs that need fixing
```
HACK:
```
- Temporary workarounds
```
NOTE:
```
- Important information or context
```
WARNING:
```
- Critical information about usage
```
PERF:
```
- Performance considerations
```
SECURITY:
```
- Security-related notes
```
BUG:
```
- Known bug documentation
```
REFACTOR:
```
- Code that needs refactoring
```
DEPRECATED:
```
- Soon-to-be-removed code

```
TODO:
```
- 待完成的工作
```
FIXME:
```
- 需要修复的已知Bug
```
HACK:
```
- 临时解决方案
```
NOTE:
```
- 重要信息或上下文
```
WARNING:
```
- 关于使用的关键提示
```
PERF:
```
- 性能相关考量
```
SECURITY:
```
- 安全相关说明
```
BUG:
```
- 已知Bug文档
```
REFACTOR:
```
- 需要重构的代码
```
DEPRECATED:
```
- 即将被移除的代码

Refactoring Over Commenting

优先重构而非注释

Instead of Commenting Complex Code...

与其为复杂代码添加注释...

BAD: Complex code with comment

python

undefined

反面示例：复杂代码加注释

python

undefined

Check if user is admin or has special permissions

if user.role == "admin" or (user.permissions and "special" in user.permissions): grant_access()

undefined

if user.role == "admin" or (user.permissions and "special" in user.permissions): grant_access()

undefined

...Extract to Named Function

...不如提取为命名函数

GOOD: Self-explanatory through naming

python

def user_has_admin_access(user):
    return user.role == "admin" or has_special_permission(user)

def has_special_permission(user):
    return user.permissions and "special" in user.permissions

if user_has_admin_access(user):
    grant_access()

正面示例：通过命名实现自我说明

python

def user_has_admin_access(user):
    return user.role == "admin" or has_special_permission(user)

def has_special_permission(user):
    return user.permissions and "special" in user.permissions

if user_has_admin_access(user):
    grant_access()

Language-Specific Examples

特定语言示例

JavaScript

javascript

// Good: Explains WHY we debounce
// Debounce search to reduce API calls (500ms wait after last keystroke)
const debouncedSearch = debounce(searchAPI, 500);

// Bad: Obvious
let count = 0;  // Initialize count to zero
count++;  // Increment count

// Good: Explains algorithm choice
// Using Set for O(1) lookup instead of Array.includes() which is O(n)
const seen = new Set(ids);

javascript

// Good: Explains WHY we debounce
// Debounce search to reduce API calls (500ms wait after last keystroke)
const debouncedSearch = debounce(searchAPI, 500);

// Bad: Obvious
let count = 0;  // Initialize count to zero
count++;  // Increment count

// Good: Explains algorithm choice
// Using Set for O(1) lookup instead of Array.includes() which is O(n)
const seen = new Set(ids);

Python

python

undefined

python

undefined

Good: Explains the algorithm choice

Using binary search because data is sorted and we need O(log n) performance

index = bisect.bisect_left(sorted_list, target)

Bad: Redundant

def get_total(items): return sum(items) # Return the sum of items

Good: Explains why we're doing this

Extract to separate function for type checking in mypy

def validate_user(user): if not user or not user.id: raise ValueError("Invalid user") return user

undefined

def validate_user(user): if not user or not user.id: raise ValueError("Invalid user") return user

undefined

TypeScript

typescript

// Good: Explains the type assertion
// TypeScript can't infer this is never null after the check
const element = document.getElementById('app') as HTMLElement;

// Bad: Obvious
const sum = a + b;  // Add a and b

// Good: Explains non-obvious behavior
// spread operator creates shallow copy; use JSON for deep copy
const newConfig = { ...config };

typescript

// Good: Explains the type assertion
// TypeScript can't infer this is never null after the check
const element = document.getElementById('app') as HTMLElement;

// Bad: Obvious
const sum = a + b;  // Add a and b

// Good: Explains non-obvious behavior
// spread operator creates shallow copy; use JSON for deep copy
const newConfig = { ...config };

Comment Quality Checklist

注释质量检查清单

Summary

总结

Priority order:

Clear code - Self-explanatory through naming and structure
Good comments - Explain WHY when necessary
Documentation - API docs, docstrings for public interfaces
No comments - Better than bad comments that lie or clutter

Remember: Comments are a failure to make the code self-explanatory. Use them sparingly and wisely.

优先级顺序：

清晰的代码 - 通过命名与结构实现自我说明
优质注释 - 必要时解释‘为什么’
文档 - 公共接口的API文档与文档字符串
无注释 - 比错误或杂乱的注释更好

请记住：注释是代码无法自我说明时的补充。要少用、慎用。

Key Takeaways

关键要点

Goal	Approach
Reduce comments	Improve naming, extract functions, simplify logic
Improve clarity	Use self-explanatory code structure, clear variable names
Document APIs	Use docstrings/JSDoc for public interfaces
Explain WHY	Comment only business logic, algorithms, workarounds
Maintain accuracy	Update comments when code changes, or remove them

目标	实现方式
减少注释	优化命名、提取函数、简化逻辑
提升清晰度	使用自解释的代码结构、清晰的变量名
文档化API	为公共接口使用文档字符串/JSDoc
解释‘为什么’	仅为业务逻辑、算法、临时解决方案添加注释
保持准确性	代码变更时更新注释，或直接删除

code-documentation

Original

Translation

Code Documentation & Self-Explanatory Code

代码文档与自解释代码

Core Principle

核心原则

The Commenting Philosophy

注释理念

When to Comment

何时添加注释

Comment Anti-Patterns

注释反模式

❌ 1. Obvious Comments

❌ 1. 显而易见的注释

❌ 2. Redundant Comments

❌ 2. 冗余注释

❌ 3. Outdated Comments

❌ 3. 过时注释

Calculate tax at 5% rate

Calculate tax at 5% rate

DEPRECATED: Use new_api_function() instead

DEPRECATED: Use new_api_function() instead

❌ 4. Noise Comments

❌ 4. 无意义注释

Start of function

Start of function

End of function

End of function

❌ 5. Dead Code & Changelog Comments

❌ 5. 死代码与变更日志注释

Don't comment out code - use version control

Don't comment out code - use version control

def old_function():

def old_function():

return "deprecated"

return "deprecated"

Don't maintain history in comments

Don't maintain history in comments

Modified by John on 2023-01-15

Modified by John on 2023-01-15

Fixed bug reported by Sarah on 2023-02-03

Fixed bug reported by Sarah on 2023-02-03

Good Comment Examples

优秀注释示例

✅ Complex Business Logic

✅ 复杂业务逻辑

Apply progressive tax brackets: 10% up to $10k, 20% above

Apply progressive tax brackets: 10% up to $10k, 20% above

This matches IRS publication 501 for 2024

This matches IRS publication 501 for 2024

✅ Non-obvious Algorithms

✅ 非显而易见的算法

Using Floyd-Warshall for all-pairs shortest paths

Using Floyd-Warshall for all-pairs shortest paths

because we need distances between all nodes.

because we need distances between all nodes.

Time: O(n³), Space: O(n²)

Time: O(n³), Space: O(n²)

✅ Regex Patterns

✅ 正则表达式

Match email format: username@domain.extension

Match email format: username@domain.extension

Allows letters, numbers, dots, hyphens in username

Allows letters, numbers, dots, hyphens in username

Requires valid domain and 2+ char extension

Requires valid domain and 2+ char extension

✅ API Constraints or Gotchas

✅ API约束或注意事项

GitHub API rate limit: 5000 requests/hour for authenticated users

GitHub API rate limit: 5000 requests/hour for authenticated users

We implement exponential backoff to handle rate limiting

We implement exponential backoff to handle rate limiting

✅ Workarounds for Bugs

✅ Bug临时解决方案

HACK: Workaround for bug in library v2.1.0

HACK: Workaround for bug in library v2.1.0

Remove after upgrading to v2.2.0

Remove after upgrading to v2.2.0

See: https://github.com/library/issues/123