变量命名与注释
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.
是否存在函数使用上的性能隐患.
如果函数是可重入的, 其同步前提是什么?
实现注释:
对于代码中巧妙的, 晦涩的, 有趣的, 重要的地方加以注释.
行注释:
比较隐晦的地方要在行尾加入注释. 在行尾空两格进行注释.
尽可能给有描述性的命名,别心疼空间,毕竟让代码易于新读者理解很重要。不要用只有项目开发者能理解的缩写,也不要通过砍掉几个字母来缩写单词。
好的代码:
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/
google 开元项目风格指南
http://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/