注释写中文还是英文？我的 PR 被拒三次后，总结出这套双语规范

三个月前，我把一个维护了两年的开源工具库的注释全部从英文换成了中文。理由很朴素：写中文注释的速度快一倍，表达也精准得多，「边界情况」「兜底逻辑」这些词，翻成英文总觉得差点意思。

然后 issue 区炸了。

第一周：礼貌的困惑

最先来的是一位德国贡献者，语气很客气："Lovely library, but could you clarify what '兜底' means in context?" 我耐心解释了。接着是巴西、印度、日本的开发者陆续提出同样的问题——不是他们不尊重中文，而是他们真的没法参与讨论一段自己读不懂的代码。

我当时的反应是典型的："这是我的项目，我开心就好。" 这个想法维持了大约两周。

第三周：PR 被拒的连锁反应

转折点是三个 PR 被连续拒绝。原因不是代码质量——代码写得很好——而是贡献者在 review 时明确说："I can't verify the logic against the comments, so I'm not comfortable approving."

这让我意识到一个被低估的事实：注释不只是写给自己看的文档，它是协作的接口。代码本身是通用语言，但注释决定了谁能参与维护。把注释换成中文，等于悄悄把项目的贡献者门槛从「会编程」提高到了「会编程且懂中文」。

开源社区的语言政治很现实：英语不是更优越，而是更通用。就像 TCP/IP 不是最快的协议，但它是所有人都在说的协议。

第四周到第十二周：摸索出一套双语规范

被教育了三个月后，我没有退回纯英文，而是形成了一套务实的混合方案，实测下来各方都还能接受：

1. 文档字符串（docstring）一律英文。这是 API 的门面，是自动生成文档的来源，是外部贡献者的第一入口。
2. 行内注释用中文 + 关键术语保留英文。例如：# 这里做兜底处理（fallback），超时后走本地缓存。中文保证团队内部思考效率，英文关键词保证搜索和翻译工具能工作。
3. TODO 和 FIXME 用英文。这些标记经常被工具（grep、CI 脚本、issue bot）扫描，统一格式收益明显。
4. 复杂算法的解释写双语，中文写思路，英文一句话概括结论。多花五分钟，省掉未来无数次的 "what does this do?"。
5. CONTRIBUTING.md 里明确声明注释语言约定。把潜规则写明白，比让贡献者猜要体面得多。

一份注释语言决策清单

如果你也在纠结，按顺序问自己四个问题：

• 这个项目的预期贡献者是谁？ 纯国内团队 → 中文无压力；面向国际的开源项目 → 英文为主。
• 这段代码的生命周期多长？ 三个月就废弃的脚本，怎么舒服怎么写；要维护五年的核心模块，按「下一个读者是陌生人」的标准来。
• 团队里有没有非中文母语者？ 有一个人，就该照顾一个人。
• 注释会不会被工具消费？ 会（文档生成、静态检查）→ 英文更稳。

写在最后

回头看，那三个月的 issue 摩擦其实是好事——它逼我把「注释给谁看」这个平时懒得想的问题想清楚了。语言没有对错，但选择语言这件事本身，就是一个架构决策，值得像选数据库一样认真对待。

现在我的仓库 README 里多了一行："Comments: Chinese for rationale, English for API docs. PRs welcome in either language."

贡献者数量，反而比全英文时期涨了 40%。