变量命名与注释

Posted 2020-07-10 张瑞东

1. 函数命名，变量命名，文件命名要有描述性；少用缩写。

尽可能给有描述性的命名，别心疼空间，毕竟让代码易于新读者理解很重要。不要用只有项目开发者能理解的缩写，也不要通过砍掉几个字母来缩写单词。

好的代码：
int price_count_reader;    // 无缩写
int num_errors;            // “num” 本来就很常见
int num_dns_connections;   // 人人都知道 “DNS” 是啥

不好的代码
int n;                     // 莫名其妙。
int nerr;                  // 怪缩写。
int n_comp_conns;          // 怪缩写。
int wgc_connections;       // 只有贵团队知道是啥意思。
int pc_reader;             // "pc" 有太多可能的解释了。
int cstmr_id;              // 有删减若干字母。


变量名一律小写, 单词之间用下划线连接. 类的成员变量以下划线结尾, 但结构体的就不用

好的代码：
string table_name;  // 可 - 用下划线。
string tablename;   // 可 - 全小写。

不好的代码：

string tableName;   // 差 - 混合大小写。




2. 注释 ： 注释的作用是为了弥补代码自身在表达上的不足;

 注释固然很重要, 但最好的代码本身应该是自文档化. 有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字.

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


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

注释位于声明之前, 对函数功能及用法进行描述. 注释使用叙述式 (“Opens the file”) 而非指令式 (“Open the file”); 注释只是为了描述函数, 而不是命令函数做什么. 通常, 注释不会描述函数如何工作. 那是函数定义部分的事情.

函数声明处注释的内容:

函数的输入输出.
对类成员函数而言: 函数调用期间对象是否需要保持引用参数, 是否会释放这些参数.
如果函数分配了空间, 需要由调用者释放.
参数是否可以为 NULL.
是否存在函数使用上的性能隐患.
如果函数是可重入的, 其同步前提是什么?

实现注释：
对于代码中巧妙的, 晦涩的, 有趣的, 重要的地方加以注释.



行注释:

比较隐晦的地方要在行尾加入注释. 在行尾空两格进行注释.

 更多信息可以参考 
google 开元项目风格指南
http://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/