如何写注释

核心原则：注释要说代码没说的事

很多程序员写的注释之所以没用，就是因为它们只是在“翻译”代码。

好例子的思考方式：

• 在写下一行注释前，先问自己一个问题：“一个新手，只看这行代码，能猜出我接下来要写的注释吗？”
• 如果答案是“能”，那这个注释就别写了。

要点一：注释要提供两种维度的信息

1. 向下钻取：提供更精确的细节(Lower-level Comments)

• 代码中的变量名和类型往往不够精确。注释需要把这些模糊地带说清楚。这就像给电影画面配上详细的字幕说明。

1. 向上提升：提供更宏观的视角(Higher-levelComments)
   • 这部分是注释最有价值的地方，它提供的是 “直觉”和“意图”。细节
     • 它不是解释代码怎么做，而是解释为什么这么做和目标是什么。
     • 这就像电影的旁白，解释一段剧情的整体目的。

要点二：接口注释是重中之重

• 接口（比如一个类或一个方法的声明）是代码的“合同”。
  • 使用你的代码的人，应该只需要阅读这份“合同”（接口和它的注释）而完全不需要关心“合同”内部是如何履行的（代码实现）。
• 接口注释要分离：
  • 接口注释（给使用者看）和实现注释 （给维护者看)要分开。
  • 如果你的接口注释不得不描述实现细节，那通常说明你的设计（抽象）做得不够好。细节

要点三：实现注释（方法内部的注释)

• 方法内部的注释主要是为了帮助维护者理解代码的内部逻辑。
• 解释“做什么”和“为什么”：
  • 对于一个比较长的函数，可以在逻辑代码块前加注释，说明这个代码块的目标。
  • 比如/第一步：清理并验证用户输入。
• 解释“奇怪”的代码：
  • 如果有一段代码看起来很绕，通常是为了解决某个特定的、不常见的问题。 这时一定要加注释说明原因

要点四：如何处理跨模块的设计决策

• 有些设计决策会影响到好几个文件/模块比如一个网络协议的设计会同时影响发送方和接收方。给这种决策写文档的难点在于：注释写在哪里才能被需要的人看到？