melech-smart-comments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smart Comments

智能注释

You are often the first reader of this code. You do not carry the scar tissue a human teammate would — you did not live through the incident that caused a function to look the way it does, and you cannot smell the landmine from the shape of the code alone.

Comments are the spec layer closest to the code. They are the last thing a model reads before producing the next token, and they are the cheapest, highest-signal way for a human to hand you constraints, warnings, and intent. Treat them accordingly.

This skill governs how you write new comments and how you treat existing ones.

你通常是这段代码的第一位阅读者。你不像人类队友那样带着过往的经验——你没有经历过导致某个函数变成当前样子的事件，也无法仅凭代码的结构察觉到潜在的隐患。

注释是最贴近代码的规范层。模型在生成下一个token前会最后读取注释，而对于人类来说，注释是传递约束、警告和意图成本最低、信号最强的方式。请据此对待注释。

本技能规定了你如何编写新注释以及如何处理现有注释。

When to Write a Comment

何时编写注释

Write an inline comment when one of these is true. Otherwise do not.

Landmines. Code that looks wrong, redundant, or removable but is not. State the reason — the past bug, the ordering constraint, the external-system quirk — so the next reader (human or agent) knows the cost of touching it.
Non-obvious WHY. When the chosen approach was picked over a cleaner-looking alternative, name the tradeoff. "We could do X, but Y happens under load" is load-bearing; without it the next reader will try X.
Hidden invariants and contracts. Implicit assumptions not visible in types, names, or the local function body — ordering between calls, idempotency guarantees, state a caller must have already set up, fields that must be populated together.
Workarounds. Bugs in external systems, race conditions, temporary version pins, polyfills, hacks waiting on an upstream fix. Link or name the issue if one exists.

当满足以下任一条件时，编写行内注释。否则请勿编写。

潜在隐患：代码看起来有误、冗余或可移除，但实际并非如此。说明原因——过往的bug、顺序约束、外部系统的特殊情况——以便下一位阅读者（人类或Agent）了解修改这段代码的代价。
非显而易见的原因：当所选方案是在比它更简洁的替代方案中筛选出来时，说明其中的权衡。“我们可以做X，但在高负载下会出现Y问题”是关键信息；如果没有这条注释，下一位阅读者会尝试使用X方案。
隐藏的不变量与约定：在类型、名称或本地函数体中不可见的隐含假设——调用顺序、幂等性保证、调用者必须预先设置的状态、必须同时填充的字段。
临时解决方案：外部系统的bug、竞态条件、临时版本锁定、polyfills、等待上游修复的临时技巧。如果有相关问题链接或编号，请附上。

When NOT to Write a Comment

何时不要编写注释

Do not write a comment when:

It narrates WHAT the code does and the identifiers already say it.
```
// increment counter
```
above
```
counter++
```
is noise.
It refers to the current task, ticket, PR, author, or review round. Those belong in the commit message or PR description. They rot in the code.
It is a banner, section divider, or restatement of the function signature.
It describes intent the code itself will carry forward reliably through refactors — if a rename makes the comment wrong, the comment was redundant.

If the WHY is obvious from the name of the function and its arguments, the comment is not paying for its space.

在以下情况请勿编写注释：

注释只是复述代码的功能，而代码标识符已经清晰表达了这一点。
```
counter++
```
上方的
```
// increment counter
```
属于冗余信息。
注释涉及当前任务、工单、PR、作者或评审轮次。这些内容属于commit message或PR描述，留在代码中会逐渐失效。
注释是横幅、章节分隔符或函数签名的重复说明。
注释描述的意图可以通过代码重构可靠地传递——如果重命名会导致注释失效，那么这条注释本身就是冗余的。

如果函数名称及其参数已经能明显体现原因，那么这条注释就没有存在的必要。

How to Write Them

如何编写注释

Inline. Directly above or beside the line they protect. Not at the top of the file, not in external docs, not in a commit message.
Short. Lead with the constraint or the warning. No wind-up.
Imperative where it matters. Prefer "Do not reorder — must run before X" over "This runs before X."
Name the cost. "Removing this early-return reopens the N+1 we fixed" beats "important early return."
If a comment needs more than about three lines, the code itself is probably wrong. Fix the code, not the comment.

行内放置：直接放在所注释代码的上方或旁边。不要放在文件顶部、外部文档或commit message中。
简洁明了：先说明约束或警告，不要铺垫。
必要时使用祈使语气：优先使用“请勿重新排序——必须在X之前运行”而非“这段代码在X之前运行”。
说明代价：“移除这个提前返回会重新触发我们修复过的N+1问题”比“重要的提前返回”更有效。
如果注释需要超过三行，那么代码本身可能存在问题。修复代码，而非注释。

Respecting Existing Comments

尊重现有注释

This section is the reason this skill exists.

Treat every existing comment as load-bearing until proven otherwise. Someone — human or past agent — paid a cost to leave it there. Assume that cost was real.
Do not delete a comment during a refactor unless the code the comment describes is also being removed. Moving code does not justify dropping its comment.
"Looks redundant" is not sufficient justification for removal. The comment may be the only surviving trace of a past incident that the code itself no longer advertises.
If a comment looks stale or wrong, flag it in your response to the user. Do not silently fix or remove it. The user is the only one who can confirm whether the comment still reflects reality.
Never rewrite a comment just to change voice or tone. If it reads as a warning, keep it as a warning.

这部分内容是本技能存在的原因。

除非被证明是冗余的，否则将每一条现有注释视为关键信息：有人——人类或之前的Agent——付出成本留下了这条注释。请假设这个成本是真实存在的。
重构期间不要删除注释，除非注释描述的代码也被移除。移动代码并不意味着可以丢弃其注释。
“看起来冗余”不足以成为删除注释的理由：这条注释可能是某个过往事件仅存的痕迹，而代码本身已不再体现该事件的信息。
如果注释看起来过时或有误，在回复用户时指出这一点。不要悄悄修改或删除它。只有用户才能确认这条注释是否仍然符合实际情况。
不要仅仅为了改变语气而重写注释：如果它是一条警告，请保留警告的语气。

Calibration Examples

校准示例

Bad — narrates what the code already says:

python

undefined

错误示例——复述代码已表达的内容：

python

undefined

Increment the retry counter

retries += 1


Good — names the landmine:
```python

retries += 1


正确示例——指出潜在隐患：
```python

Do not switch to exponential backoff here; upstream rate-limits on burst, not on average.

retries += 1


Bad — rots on the next refactor:
```ts
// Added in PR #4821 by @alice to handle the new billing webhook
if (event.type === "invoice.paid") { ... }

Good — preserves the WHY:

// Stripe fires invoice.paid before invoice.finalized for auto-advancing subs; handle both orderings.
if (event.type === "invoice.paid") { ... }

Bad — decorative, adds no signal:

// ---------- Helpers ----------

Good — encodes a hidden contract:

// Caller must hold s.mu. Returns the unwrapped value; safe only until the next Set().
func (s *state) peek() T { ... }

retries += 1


错误示例——重构后会失效：
```ts
// Added in PR #4821 by @alice to handle the new billing webhook
if (event.type === "invoice.paid") { ... }

正确示例——保留原因：

// Stripe fires invoice.paid before invoice.finalized for auto-advancing subs; handle both orderings.
if (event.type === "invoice.paid") { ... }

错误示例——装饰性内容，无实际意义：

// ---------- Helpers ----------

正确示例——明确隐藏的约定：

// Caller must hold s.mu. Returns the unwrapped value; safe only until the next Set().
func (s *state) peek() T { ... }

Summary

总结

Code shows movement. Comments preserve memory. You are the reader that will most often decide whether that memory survives the next edit. When in doubt, leave the comment, and ask the human whether it should go.

代码展示执行逻辑。注释保留历史经验。你是最常决定这些经验能否在下次编辑中留存的阅读者。如有疑问，请保留注释，并询问用户是否应该移除它。