在跨国团队和开源项目里,一份代码配两种语言注释并不少见:函数头上中文写一句、英文再写一句,或者中文注释是三年前写的,英文注释是上个月补的。时间一长,两边说法对不上就成了常态:中文说参数可以为空,英文说必填;中文写着已经废弃,英文还写着推荐使用。读代码的人不知道该信哪一句,改代码的人也不敢动注释,最后注释慢慢变成摆设。
问题根源不在翻译水平,而在管理方式。第一,注释与代码不同步:代码改了,注释没人改,两种语言的注释又由不同的人在不同时间维护,偏差只会越拉越大。第二,注释写了不该写的东西:把代码本身就能表达的逻辑复述一遍,一旦逻辑改了,两处复述都要改,改漏就是不一致。第三,术语没有统一口径:同一个概念中文有两三种叫法,英文缩写也不固定,对照起来自然对不上。
管用的做法是先给注释减负,再给同步立规矩。注释只写代码看不出来的东西:为什么这样设计、有什么边界条件、哪些坑不能踩;至于做了什么,让代码自己说。术语表放进仓库,和代码一起评审、一起发布,新增术语先入库再使用。双语注释不要各写各的:以一种语言为主版本,另一种语言明确标注为译文,译文只做翻译、不独立补充信息,主版本一改,译文就进入待更新状态。
落地时可以分三步走。新代码要求注释与代码同一次提交、同一轮评审,评审清单里单列注释一致性一项;旧注释不必一次性全改,按模块分批对齐,先对齐对外接口和高频模块;再给仓库加一道轻量检查,例如提交时提醒改动函数是否同步更新了注释。注释的价值在于可信,一份说法统一的注释,胜过两份各说各话的注释。
更长远看,注释一致性也是新人上手速度的决定因素之一:说法统一的注释能让新人少走弯路,而互相矛盾的注释只会让人对整份文档失去信任,最后连正确的注释也没人敢信了。