会不会写注释，有没有写注释的意识，是工程师的基本素养之一，因 - 沸点

Bison @北京

会不会写注释，有没有写注释的意识，是工程师的基本素养之一，因为你至少明白，你写的代码不只是实现功能，还要供他人维护。有效的注释可以降低业务代码的“接班人痛苦指数”。

代码即注释，确实是值得追求的目标，也是应该坚守的原则，但问题是：做得到吗？做到了吗？

至少以下场景是需要写注释的：

1、无法由代码本身体现的隐含的背景知识，不写出来别人根本不知道，或者获知的成本很高。这一条是最重要的，看上去是个小事，写和不写，天差地别。在 review 的时候，如果你看不懂某块代码在干什么，就应该要求补注释；

2、描述同一个功能的大段代码块，通过注释，可以避免他人在代码细节中花费过多不必要的时间；

3、供他人调用的组件、接口、方法，需要写注释（微服务的文档）；

4、英文表义不够直白、清晰、准确，则应该写注释；

5、非通识的缩写应该给出缩写的完整含义；

6、接口定义的地方，提供接口文档链接（如果接口文档很难找的话）；

7、针对某个业务需求的组件，提供相关文档链接；

注释有可能得不到及时更新，有可能出错，但从实践来看，最主要的问题还是在于压根儿没写。

展开

等人赞过