8.4. 函数注释

总述

函数声明处的注释描述函数功能; 定义处的注释描述函数实现.

说明

函数声明

基本上每个函数声明处前都应当加上注释, 描述函数的功能和用途. 只有在函数的功能简单而明显时才能省略这些注释(例如, 简单的取值和设值函数). 注释使用叙述式 (“Opens the file”) 而非指令式 (“Open the file”); 注释只是为了描述函数, 而不是命令函数做什么. 通常, 注释不会描述函数如何工作. 那是函数定义部分的事情.

函数声明处注释的内容:

  • 函数的输入输出.
  • 对类成员函数而言: 函数调用期间对象是否需要保持引用参数, 是否会释放这些参数.
  • 函数是否分配了必须由调用者释放的空间.
  • 参数是否可以为空指针.
  • 是否存在函数使用上的性能隐患.
  • 如果函数是可重入的, 其同步前提是什么?
    举例如下:
  1. // Returns an iterator for this table.  It is the client's
  2. // responsibility to delete the iterator when it is done with it,
  3. // and it must not use the iterator once the GargantuanTable object
  4. // on which the iterator was created has been deleted.
  5. //
  6. // The iterator is initially positioned at the beginning of the table.
  7. //
  8. // This method is equivalent to:
  9. //    Iterator* iter = table->NewIterator();
  10. //    iter->Seek("");
  11. //    return iter;
  12. // If you are going to immediately seek to another place in the
  13. // returned iterator, it will be faster to use NewIterator()
  14. // and avoid the extra seek.
  15. Iterator* GetIterator() const;

但也要避免罗罗嗦嗦, 或者对显而易见的内容进行说明. 下面的注释就没有必要加上 “否则返回 false”, 因为已经暗含其中了:

  1. // Returns true if the table cannot hold any more entries.
  2. bool IsTableFull();

注释函数重载时, 注释的重点应该是函数中被重载的部分, 而不是简单的重复被重载的函数的注释. 多数情况下, 函数重载不需要额外的文档, 因此也没有必要加上注释.

注释构造/析构函数时, 切记读代码的人知道构造/析构函数的功能, 所以 “销毁这一对象” 这样的注释是没有意义的. 你应当注明的是注明构造函数对参数做了什么 (例如, 是否取得指针所有权) 以及析构函数清理了什么. 如果都是些无关紧要的内容, 直接省掉注释. 析构函数前没有注释是很正常的.

函数定义

如果函数的实现过程中用到了很巧妙的方式, 那么在函数定义处应当加上解释性的注释. 例如, 你所使用的编程技巧, 实现的大致步骤, 或解释如此实现的理由. 举个例子, 你可以说明为什么函数的前半部分要加锁而后半部分不需要.

不要 从 .h 文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上.