函数注释

人们不喜欢写注释的一个常见原因是“它们只是在陈述已经很明显的东西”，所以注释是多余的。对于一般性的注释，确实难以反驳，特别是在面向对象语言的封装方面。一些简单的函数，比如 get_temperature() 的一般性描述可能如下所示：

/**
* Returns the temperature.
*/
int get_temperature(void) {
  return temperature;
}

这里的注释确实没有增加太多的价值，它本质上只是重复了函数的名字，只是在说明这个函数的作用。这不是我们想要的，我们想要的是代码没有告诉我们的东西。

这个函数非常简单，所以写注释是绝对没有必要的。但话又说回来，软件开发当中没有什么东西是真正简单的。如果你够仔细，就会发现每个函数都有值得写的东西，而这些东西并不能从它的名字甚至是简单的一两行代码中看出来。

/**
* Returns the temperature in tenth degrees Celsius
* in range [0..1000], or -1 in case of an error.
*
* The temperature itself is set in the periodically
* executed read_temperature() function.
*
* Make sure to call init_adc() before calling this
* function here, or you will get undefined data.
*/
int get_temperature(void) {
  return temperature;
}

每个函数都有自己的特点，至少会有一个细节、副作用、异常、限制，等等，它们都值得写出来，这意味着你可能需要从不同的角度来看待这个函数，才能找出它们。为此，你不可避免地要沉浸在代码隐藏的细节当中，这样才可能发现一些之前没有想到过的特殊情况。因此，代码注释不仅可以帮助读代码的人理解代码，还能帮助写代码的人更好地了解代码的内部细节。 如果你确实找不到有用的信息，那么应该问问自己为什么要写这些代码。这些代码存在的理由是什么？而这些理由就是有用的信息。之前的例子也可以是这样：

/**
* Returns the temperature.
*
* This is for testing purpose only and should
* never be called from a real program.
*/
int get_temperature(void) {
  return temperature;
}

请注意，这段代码与之前完全相同，于是这又把我们引向了另一个问题“看似自解释的代码的注释通常都很简单”：它可能含糊不清，可能会导致错误的假设和潜在的缺陷。指出这些细节并消除潜在的歧义对于提升代码质量来说至关重要，这说明注释应该成为代码的重要组成部分。

同样，如果不深入研究代码，就无法发现每个函数的特点。当然，在这些不起眼的细节中，总有一些比另外一些更值得我们注意，并不是说函数所涉及的东西都会很有趣。认知偏差的范围很广，有些东西在这个时刻对你来说是显而易见的，并不意味着对于其他人来说也是这样——包括未来的你。