8.5. 变量注释

总述

通常变量名本身足以很好说明变量用途. 某些情况下, 也需要额外的注释说明.

说明

类数据成员

每个类数据成员 (也叫实例变量或成员变量) 都应该用注释说明用途. 如果有非变量的参数(例如特殊值, 数据成员之间的关系, 生命周期等)不能够用类型与变量名明确表达, 则应当加上注释. 然而, 如果变量类型与变量名已经足以描述一个变量, 那么就不再需要加上注释.

特别地, 如果变量可以接受 NULL 或 -1 等警戒值, 须加以说明. 比如:

  1. private:
  2.  // Used to bounds-check table accesses. -1 means
  3.  // that we don't yet know how many entries the table has.
  4.  int num_total_entries_;

全局变量

和数据成员一样, 所有全局变量也要注释说明含义及用途, 以及作为全局变量的原因. 比如:

  1. // The total number of tests cases that we run through in this regression test.
  2. const int kNumTestCases = 6;