|
|
# 02 | 编码阶段能做什么：秀出好的code style
|
|
|
|
|
|
你好，我是Chrono。
|
|
|
|
|
|
上节课我介绍了C++程序的生命周期和编程范式，今天我就接着展开来讲，看看在编码阶段我们能做哪些事情。
|
|
|
|
|
|
在编码阶段，我们的核心任务就是写出在预处理、编译和运行等不同阶段里执行的代码，还记得那句编程格言吗：
|
|
|
|
|
|
“**任何人都能写出机器能看懂的代码，但只有优秀的程序员才能写出人能看懂的代码。**”
|
|
|
|
|
|
所以，我们在编码阶段的首要目标，不是实现功能，而是要写出清晰易读的代码，也就是要有好的code style。
|
|
|
|
|
|
怎么样才能写出human readable的好代码呢？
|
|
|
|
|
|
这就需要有一些明确的、经过实践验证的规则来指导，只要自觉遵守、合理运用这些规则，想把代码写“烂”都很难。
|
|
|
|
|
|
在此，我强烈推荐一份非常棒的[指南](http://openresty.org/cn/c-coding-style-guide.html)，它来自OpenResty的作者章亦春，代码风格参照的是顶级开源产品Nginx，内容非常详细完善。
|
|
|
|
|
|
不过有一点要注意，这份指南描述的是C语言，但对于C++仍然有很好的指导意义，所以接下来我就以它为基础，加上我的工作体会，从**代码格式**、**标识符命名**和**注释**三个方面，讲一下怎么“秀出好的code style”。
|
|
|
|
|
|
## 空格与空行
|
|
|
|
|
|
当我们拿到一份编码风格指南的时候，不论它是公司内部的还是外部的，通常第一感觉就是“头大”，几十个、上百个的条款罗列在一起，规则甚至细致到了标点符号，再配上干巴巴的说明和示例，不花个半天功夫是绝对看不完的。而且，最大的可能是半途而废，成了“从入门到放弃”。
|
|
|
|
|
|
我写了很多年代码，也看过不少这样的文档，我从中总结出了一条最基本、最关键的规则，只要掌握了这条规则，就可以把你code style的“颜值”起码提高80%。
|
|
|
|
|
|
这条“神奇”的规则是什么呢？
|
|
|
|
|
|
认真听，只有五个字：**留白的艺术**。
|
|
|
|
|
|
再多说一点，就是像“写诗”一样去写代码，**恰当地运用空格和空行**。不要为了“节省篇幅”和“紧凑”而把很多语句挤在一起，而是要多用空格分隔开变量与操作符，用空行分隔开代码块，保持适当的阅读节奏。
|
|
|
|
|
|
你可以看看下面的这个示例，这是我从某个实际的项目中摘出来的真实代码（当然，我隐去了一些敏感信息）：
|
|
|
|
|
|
```
|
|
|
if(!value.contains("xxx")){
|
|
|
LOGIT(WARNING,"value is incomplete.\n")
|
|
|
return;
|
|
|
}
|
|
|
char suffix[16]="xxx";
|
|
|
int data_len = 100;
|
|
|
if(!value.empty()&&value.contains("tom")){
|
|
|
const char* name=value.c_str();
|
|
|
for(int i=0;i<MAX_LEN;i++){
|
|
|
... // do something
|
|
|
}
|
|
|
int count=0;
|
|
|
for(int i=0;i<strlen(name);i++){
|
|
|
... // do something
|
|
|
}
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
这段代码真可谓是“高密度”，密密麻麻一大堆，看着“有如滔滔江水，连绵不绝”，读起来让人“窒息”，code style非常糟糕。
|
|
|
|
|
|
应用“留白的艺术”，代码就变成了下面的样子：
|
|
|
|
|
|
```
|
|
|
if (!value.contains("xxx")) { // if后{前有空格
|
|
|
LOGIT(WARNING, "value is incomplete.\n") // 逗号后有空格
|
|
|
return; // 逻辑联系紧密就不用加空行
|
|
|
}
|
|
|
// 新增空行分隔段落
|
|
|
char suffix[16] = "xxx"; // 等号两边有空格
|
|
|
int data_len = 100; // 逻辑联系紧密就不用加空行
|
|
|
// 新增空行分隔段落
|
|
|
if (!value.empty() && value.contains("tom")) { // &&两边有空格
|
|
|
const char* name = value.c_str(); // 等号两边有空格
|
|
|
// 新增空行分隔段落
|
|
|
for(int i = 0; i < MAX_LEN; i++){ // =;<处有空格
|
|
|
... // do something
|
|
|
}
|
|
|
// 新增空行分隔段落
|
|
|
int count = 0; // 等号两边有空格
|
|
|
// 新增空行分隔段落
|
|
|
for(int i = 0; i < strlen(name); i++){ // =;<处有空格
|
|
|
... // do something
|
|
|
}
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
加上了适当的空格和空行后，代码就显得错落有致，舒缓得当，看着就像是莎翁的十四行诗，读起来不那么累，也更容易理清楚代码的逻辑。
|
|
|
|
|
|
我还有个私人观点：**好程序里的空白行至少要占到总行数的20%以上**。虽然比较“极端”，但也不失为一个可量化的指标，你可以在今后的实际工作中尝试一下。
|
|
|
|
|
|
## 起个好名字
|
|
|
|
|
|
有了好的代码格式，接下来我们要操心的就是里面的内容了，而其中一个很重要的部分就是为变量、函数、类、项目等起一个好听易懂的名字。
|
|
|
|
|
|
这里有一个广泛流传的笑话：“**缓存失效与命名是计算机科学的两大难题**。”把起名字与缓存失效（也有说是并发）相提并论，足见它有多么重要了，值得引起你的重视。
|
|
|
|
|
|
但其实命名这件事并不难，主要就在于平时的词汇和经验积累，知道在什么情况下用哪个单词最合适，千万不要偷懒用“谜之缩写”和汉语拼音（更有甚者，是汉语拼音的缩写）。由于现在搜索引擎、电子词典都很发达，只要你有足够认真的态度，在网上一搜，就能够找到合适的名字。
|
|
|
|
|
|
另外，你还可以用一些已经在程序员之间形成了普遍共识的变量名，比如用于循环的i/j/k、用于计数的count、表示指针的p/ptr、表示缓冲区的buf/buffer、表示变化量的delta、表示总和的sum……
|
|
|
|
|
|
关于命名的风格，我所知道的应用比较广的有三种。
|
|
|
|
|
|
第一种风格叫“匈牙利命名法”，在早期的Windows上很流行，使用前缀i/n/sz等来表示变量的类型，比如iNum/szName。它把类型信息做了“硬编码”，不适合代码重构和泛型编程，所以目前基本上被淘汰了。
|
|
|
|
|
|
不过它里面有一种做法我还是比较欣赏的，就是给成员变量加“m\_”前缀（member），给全局变量加“g\_”前缀（global），比如m\_count、g\_total，这样一看就知道了变量的作用域，在大型程序里还是挺有用的。
|
|
|
|
|
|
第二种风格叫“CamelCase”，也就是“驼峰式命名法”，在Java语言里非常流行，主张单词首字母大写，比如MyJobClass、tryToLock，但这种风格在C++世界里的接受程度不是太高。
|
|
|
|
|
|
第三种风格叫“snake\_case”，用的是全小写，单词之间用下划线连接。这是C和C++主要采用的命名方式，看一下标准库，里面的vector、unordered\_set、shrink\_to\_fit都是这样。
|
|
|
|
|
|
那么，你该选用哪种命名风格呢？
|
|
|
|
|
|
我的建议是“取百家之长”，混用这几种中能够让名字辨识度最高的那些优点，就是四条规则：
|
|
|
|
|
|
1. 变量、函数名和名字空间用snake\_case，全局变量加“g\_”前缀；
|
|
|
2. 自定义类名用CamelCase，成员函数用snake\_case，成员变量加“m\_”前缀；
|
|
|
3. 宏和常量应当全大写，单词之间用下划线连接；
|
|
|
4. 尽量不要用下划线作为变量的前缀或者后缀（比如\_local、name\_），很难识别。
|
|
|
|
|
|
下面我举几个例子，你一看就能明白了：
|
|
|
|
|
|
```
|
|
|
#define MAX_PATH_LEN 256 //常量，全大写
|
|
|
|
|
|
int g_sys_flag; // 全局变量，加g_前缀
|
|
|
|
|
|
namespace linux_sys { // 名字空间，全小写
|
|
|
void get_rlimit_core(); // 函数，全小写
|
|
|
}
|
|
|
|
|
|
class FilePath final // 类名，首字母大写
|
|
|
{
|
|
|
public:
|
|
|
void set_path(const string& str); // 函数，全小写
|
|
|
private:
|
|
|
string m_path; // 成员变量，m_前缀
|
|
|
int m_level; // 成员变量，m_前缀
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
命名另一个相关的问题是“名字的长度”，有人喜欢写得长，有人喜欢写得短，我觉得都可以，只要易读易写就行。
|
|
|
|
|
|
不过一个被普遍认可的原则是：**变量/函数的名字长度与它的作用域成正比**，也就是说，局部变量/函数名可以短一点，而全局变量/函数名应该长一点。
|
|
|
|
|
|
想一下，如果你辛辛苦苦起了一个包含四五个单词的长名字，却只能在短短十几行的循环体里使用，岂不是太浪费了？
|
|
|
|
|
|
## 用好注释
|
|
|
|
|
|
写出了有好名字的变量、函数和类还不够，要让其他人能“一眼”看懂代码，还需要加上注释。
|
|
|
|
|
|
“注释”在任何编程语言里都是一项非常重要的功能，甚至在编程语言之外，比如配置文件（ini、yml）、标记语言（html、xml），都有注释。一个突出的反例就是JSON，没有注释功能让许多人都很不适应。
|
|
|
|
|
|
注释表面上的功能很简单，就是给代码配上额外的文字，起到注解、补充说明的作用。但就像是写文章一样，写些什么、写多写少、写成什么样子，都是大有讲究的。
|
|
|
|
|
|
你可能也有不少写注释的经验了，一般来说，注释可以用来阐述目的、用途、工作原理、注意事项等代码本身无法“自说明”的那些东西。
|
|
|
|
|
|
但要小心，注释必须要正确、清晰、有效，尽量言简意赅、点到为止，不要画蛇添足，更不能写出含糊、错误的注释。
|
|
|
|
|
|
比如说，有这么一个模板函数get\_value：
|
|
|
|
|
|
```
|
|
|
template<typename T>
|
|
|
int get_value(const T& v);
|
|
|
|
|
|
```
|
|
|
|
|
|
代码很简单，但可用的信息太少了，你就可以给它加上作者、功能说明、调用注意事项、可能的返回值，等等，这样看起来就会舒服得多：
|
|
|
|
|
|
```
|
|
|
// author : chrono
|
|
|
// date : 2020-xx-xx
|
|
|
// purpose : get inner counter value of generic T
|
|
|
// notice : T must have xxx member
|
|
|
// notice : return value maybe -1, means xxx, you should xxx
|
|
|
template<typename T>
|
|
|
int get_value(const T& v);
|
|
|
|
|
|
```
|
|
|
|
|
|
你可能注意到了，在注释里我都用的是英文，因为英文（ASCII，或者说是UTF-8）的“兼容性”最好，不会由于操作系统、编码的问题变成无法阅读的乱码，而且还能够锻炼自己的英语表达能力。
|
|
|
|
|
|
不过，用英文写注释的同时也对你提出了更高的要求，最基本的是**不要出现低级的语法、拼写错误**。别笑，我就经常见到有人英文水平不佳，或者是“敷衍了事”，写出的都是“Chinglish”，看了让人哭笑不得。
|
|
|
|
|
|
写注释最好也要有一些标准的格式，比如用统一的“标签”来标记作者、参数说明什么的。这方面我觉得你可以参考Javadoc，它算是一个不错的工程化实践。
|
|
|
|
|
|
对于C++来说，也有一个类似的工具叫Doxgen，用好它甚至可以直接从源码生成完整的API文档。不过我个人觉得，Doxgen的格式有些过于“死板”，很难严格执行，是否采用就在于你自己了。
|
|
|
|
|
|
除了给代码、函数、类写注释，我还建议**最好在文件的开头写上本文件的注释**，里面有文件的版权声明、更新历史、功能描述，等等。
|
|
|
|
|
|
下面这个就是我比较常用的一个文件头注释，简单明了，你可以参考一下。
|
|
|
|
|
|
```
|
|
|
// Copyright (c) 2020 by Chrono
|
|
|
//
|
|
|
// file : xxx.cpp
|
|
|
// since : 2020-xx-xx
|
|
|
// desc : ...
|
|
|
|
|
|
```
|
|
|
|
|
|
另外，注释还有一个很有用的功能就是todo，作为功能的占位符，提醒将来的代码维护者（也许就是你），比如：
|
|
|
|
|
|
```
|
|
|
// TODO: change it to unordered_map
|
|
|
// XXX: fixme later
|
|
|
|
|
|
```
|
|
|
|
|
|
总的来说，要写好注释，你要时刻“换位思考”，设身处地去想别人怎么看你的代码，这样的话，上面的那些细则也就不难实施了。
|
|
|
|
|
|
## 小结
|
|
|
|
|
|
在编码阶段，拥有一个良好的编程习惯和态度是非常重要的（我见过太多对此漫不经心的“老”程序员）。今天，我只介绍了三个最基本的部分，再来“敲黑板”画个重点：
|
|
|
|
|
|
1. 用好空格和空行，多留白，让写代码就像写诗一样；
|
|
|
2. 给变量、函数、类起个好名字，你的代码就成功了一半；
|
|
|
3. 给变量、函数、类再加上注释，让代码自带文档，就成了“人能够看懂的代码”。
|
|
|
|
|
|
有了这个基础，你还可以更进一步，使用其他高级规则写出更好的代码，比如函数体不能太长、入口参数不宜过多，避免使用else/switch导致层次太深（圈复杂度），等等，这些虽然也很有用但比较琐碎，暂时就不细说了。
|
|
|
|
|
|
对了，还有一招“必杀技”：善用code review，和你周围的同事互相审查代码，可以迅速改善自己的code style。
|
|
|
|
|
|
## 课下作业
|
|
|
|
|
|
最后是课下作业时间，给你留两个思考题：
|
|
|
|
|
|
1. 你用过哪些好的code style，你最喜欢今天介绍的哪几条？
|
|
|
2. 注释在代码里通常的作用是“说明文档”，但它还有另外一个重要的用法，你知道吗？
|
|
|
|
|
|
欢迎你在留言区写下你的思考和答案，如果觉得对你有所帮助，也欢迎分享给你的朋友，我们下节课见。
|
|
|
|
|
|
|
|
|
|