$ loading_
帮助开发者为代码补充设计意图注释，聚焦原因与关键取舍而非表面功能。
复制安装指令，让 AI 自动完成配置 · 推荐新手
请帮我安装 askskill 上的 "Commenting Intent" 技能： 1. 下载 https://raw.githubusercontent.com/obra/clank/main/skills/coding/commenting-intent/SKILL.md 2. 保存为 ~/.claude/skills/commenting-intent/SKILL.md 3. 装好后重载技能，告诉我可以用了
请阅读下面这段函数代码，只为“为什么这样实现”和“不明显的设计取舍”添加注释，不要解释每一行在做什么。输出带注释的代码，并单独列出你补充注释的依据。
一份补充了意图性注释的代码，以及对应的设计原因说明。
下面代码里的注释大多是在重复代码含义。请找出这些低价值注释，删除或改写为说明业务背景、边界条件、性能考虑或兼容性原因的注释，并解释你的修改原则。
一版去除机械性注释、保留意图说明的代码，以及注释优化原则。
请从代码评审角度检查这段改动，指出哪些地方应该补充注释来说明设计意图、历史限制、失败兜底或安全考虑。按“位置—建议注释—原因”格式输出。
按位置整理的注释补充建议，帮助团队在评审中提升代码可维护性。
Good comments explain WHY, not WHAT. Code already shows what it does. Comments should explain intent, decisions, and non-obvious reasoning.
Core principle: If the comment just restates the code, delete the comment or improve the code.
Agents comment mechanics (what code does):
❌ Over-commenting (baseline):
# Calculate subtotal by multiplying price and quantity for each item, then summing
subtotal = sum(item.price * item.quantity for item in items)
# Calculate tax amount based on the subtotal and tax rate
tax = subtotal * tax_rate
# Calculate final total by adding subtotal and tax
total = subtotal + tax
Problem: Comments just restate obvious code. No value added.
✅ Comment intent only:
def calculate_total_price(items, tax_rate):
"""Calculate order total including tax."""
subtotal = sum(item.price * item.quantity for item in items)
tax = subtotal * tax_rate
return subtotal + tax # No comments needed - code is clear
✅ WHY you chose this approach:
def is_rate_limited(user_id, redis_client):
# Using Redis instead of in-memory to support distributed rate limiting
# across multiple app servers. Limit: 100 req/min per business requirements.
key = f"rate_limit:{user_id}"
current = redis_client.get(key)
if current is None:
redis_client.setex(key, 60, 1) # 60 sec TTL
return False
return int(current) >= 100 # Limit per product requirements doc
Explains: WHY Redis, WHY these limits, WHERE requirements came from.
✅ WHY this algorithm:
def find_user(users, email):
# Binary search requires sorted array. We sort by email on load
# to enable O(log n) lookups. Worth the upfront sort cost because
# lookups happen 100x more frequently than updates.
return binary_search(users, email)
Explains: WHY binary search, WHY pre-sorted, trade-off reasoning.
✅ WHY these values:
MAX_RETRIES = 3 # Testing showed 3 retries handles 99.9% of transient failures
TIMEOUT_MS = 5000 # API SLA guarantees < 5sec response time
BATCH_SIZE = 100 # Larger batches caused memory issues in prod (incident #1234)
Explains: WHERE values came from (testing, SLA, incident).
✅ WHY unusual code:
# WORKAROUND: Library bug #456 - must call reset() twice
# Fixed in v2.0 but we're on v1.8
client.reset()
client.reset()
Warns future maintainer: Unusual code has reason, link to issue.
❌ Restates the code:
# Set user name to "John"
user.name = "John"
# Loop through items
for item in items:
# Process the item
process(item)
✅ Let code speak:
user.name = "John"
for item in items:
process(item)
❌ Obvious pattern:
# Initialize search boundaries to cover entire array
left, right = 0, len(arr) - 1
# Continue searching while there's a valid range
while left <= right:
✅ Comment intent only:
def binary_search(arr, target):
# Binary search for O(log n) performance on sorted array
left, right = 0, len(arr) - 1
while left <= right:
# ... implementation (standard pattern, no comments needed)
For each comment, ask:
Does it explain WHY, not WHAT?
Would I understand without it?
Does it add information beyond the code?
| Comment This | Don't Comment This |
|---|
…
帮助你为变量选择清晰准确、易维护的命名，提升代码可读性。
帮助用户用接口封装实现细节，从业务层面设计与理解系统