很多人写注释的标准是「能写就写」，理由是「对后来人友好」。这个标准看似无害，其实代价不小——只是代价会延迟出现。
注释和代码一样需要维护
一段代码改动以后，注释如果不同步更新，就会变成谎言。谎言比沉默更糟。读到一段不一致的注释，读者要么相信了它写错代码，要么不信它白看了一段文字。无论哪种结果都不如没有注释。
现实里没有人会逐字检查注释和代码是否一致——评审注释更累，工具也很难做这件事。所以注释会比代码更快腐烂。
代码会被编译，注释只会被相信。
好的代码本身已经在说话
如果一个函数名叫 `parseUserName(input)`、参数叫 `firstName`、返回类型叫 `NormalizedName`，读者已经知道它在干什么。这时再写一行 `// 解析用户姓名` 是噪音。
需要补充的，是代码无法表达的部分：为什么这样写、有哪些前置假设、绕开了什么坑。这些才是注释真正应该承担的工作。
判断一条注释要不要写，问自己：
如果半年后回来读，仅靠这段代码本身能不能推出这条信息？能 —— 这条注释多余；不能 —— 写下去，并写清楚原因。
三类注释通常值得保留
一是关于「为什么」的注释：解释一段反直觉做法的来由，例如「这里用了 setTimeout(0) 是为了绕开某个上游库的事件顺序 bug」。
二是关于「不变量」的注释：声明一段代码必须满足的前置或后置条件，例如「调用前请确保 lock 已持有」。
三是关于「外部约束」的注释：链接到设计文档、issue、监管要求等代码本身无法承载的上下文。
默认不写，而不是默认写
把「写注释」当作一种例外，而不是常态。这样团队会被迫先去想清楚命名、再去想清楚抽象，最后才考虑要不要解释。命名和抽象做好了，多数注释就不需要存在。
代码是给计算机读的，也是给同事读的。给同事的那份，最好用结构来讲，而不是用旁注来讲。