在项目赶进度的深夜，小李接手了同事留下的模块，打开代码一看，满屏函数像天书。一个计算订单总价的方法里写着 calc()，点进去绕了三层嵌套，愣是花了半小时才搞明白哪个变量控制优惠叠加。这种场景，在缺乏注释规范的团队里太常见。
为什么注释不是可选项
很多人觉得“好代码自解释”，但现实是，代码写出来那一刻就已经开始老化。三个月后你再看自己写的逻辑，可能也得挠头。尤其在多人协作中，不写注释就像把钥匙藏起来还指望别人能开门。
比如，有个处理用户权限的方法叫 checkAccess()，表面看是判断能否进入页面，实际还包含了埋点上报和异常计数。如果不加说明，其他成员很容易误用或漏改关联逻辑。
团队该怎么定注释规矩
统一标准比写不写更重要。我们组现在强制三类必须注释：
- 公共接口和导出方法
- 复杂逻辑分支（比如超过两个条件的 if 嵌套）
- 涉及业务规则的数值（像“30”代表试用期天数，“2”代表VIP等级）
注释内容不是写“这里做个循环”，而是说清楚“为什么这么做”。例如：
/**
* 根据用户类型和活动状态计算折扣
* 注意：新人专享价不可与满减券叠加，避免资损
* @param {number} basePrice - 原价
* @param {string} userType - 用户类型：new、old、vip
* @returns {number} 最终价格
*/
function calculateDiscount(basePrice, userType) {
// ...逻辑实现
}别让注释变成负担
有些团队走极端，要求每行都注释，结果代码一半是注释。这反而让人懒得维护。我们只盯关键点：只要别人接手时不会卡住，就算达标。
上线前 Code Review 时，如果发现某段逻辑看不懂，第一反应不是问作者，而是看他有没有写注释。没有？那就打回去补上。几次之后，大家自然就习惯了。
注释不是写给机器看的，是写给人的。尤其是那个未来要改你代码的人——说不定就是你自己。