你好，我是Chrono。
上节课我介绍了C++程序的生命周期和编程范式，今天我就接着展开来讲，看看在编码阶段我们能做哪些事情。
在编码阶段，我们的核心任务就是写出在预处理、编译和运行等不同阶段里执行的代码，还记得那句编程格言吗：
“任何人都能写出机器能看懂的代码，但只有优秀的程序员才能写出人能看懂的代码。”
所以，我们在编码阶段的首要目标，不是实现功能，而是要写出清晰易读的代码，也就是要有好的code style。
怎么样才能写出human readable的好代码呢？
这就需要有一些明确的、经过实践验证的规则来指导，只要自觉遵守、合理运用这些规则，想把代码写“烂”都很难。
在此，我强烈推荐一份非常棒的指南，它来自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都是这样。
那么，你该选用哪种命名风格呢？
我的建议是“取百家之长”，混用这几种中能够让名字辨识度最高的那些优点，就是四条规则：
- 变量、函数名和名字空间用snake_case，全局变量加“g_”前缀；
- 自定义类名用CamelCase，成员函数用snake_case，成员变量加“m_”前缀；
- 宏和常量应当全大写，单词之间用下划线连接；
- 尽量不要用下划线作为变量的前缀或者后缀（比如_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
总的来说，要写好注释，你要时刻“换位思考”，设身处地去想别人怎么看你的代码，这样的话，上面的那些细则也就不难实施了。
小结
在编码阶段，拥有一个良好的编程习惯和态度是非常重要的（我见过太多对此漫不经心的“老”程序员）。今天，我只介绍了三个最基本的部分，再来“敲黑板”画个重点：
- 用好空格和空行，多留白，让写代码就像写诗一样；
- 给变量、函数、类起个好名字，你的代码就成功了一半；
- 给变量、函数、类再加上注释，让代码自带文档，就成了“人能够看懂的代码”。
有了这个基础，你还可以更进一步，使用其他高级规则写出更好的代码，比如函数体不能太长、入口参数不宜过多，避免使用else/switch导致层次太深（圈复杂度），等等，这些虽然也很有用但比较琐碎，暂时就不细说了。
对了，还有一招“必杀技”：善用code review，和你周围的同事互相审查代码，可以迅速改善自己的code style。
课下作业
最后是课下作业时间，给你留两个思考题：
- 你用过哪些好的code style，你最喜欢今天介绍的哪几条？
- 注释在代码里通常的作用是“说明文档”，但它还有另外一个重要的用法，你知道吗？
欢迎你在留言区写下你的思考和答案，如果觉得对你有所帮助，也欢迎分享给你的朋友，我们下节课见。
精选留言
2020-05-09 20:35:00
1. 匈牙利命名真心不推荐了，参考《clean code》中关于avoid encoding的说明。
2. 如果是存现代c++工程，不考虑兼容C的话. Header guards可以使用#pragma once替代。
3. 避免注释，最好使用代码来阐述。很多信息可以通过代码仓库来表达，比如commit message。
4. m_，g_ 等前缀如果使用现代化的ide的话，也可以考虑省略，因为ide的高亮能够区分。
5. 如果不是在写类库，比如开发应用程序，最好命名规则能快速区分这个是你的代码，还是标准库、知名类库的代码，可能这也是大厂流行CamalCase的缘由。
6. Google的style guide是个不错的参考，但是也有很多不可取的规则，感觉原因：Google出这个guide的时候modern c++还没有流行，Google当时内部还有很多技术债，Google想把c++写的像java。所以Google后来在golang里面....
7. 如果是参与现有项目，无论现有规则多么的不爽，都先遵循现有的规则。
2020-05-09 11:01:56
1、之所以讲究编码风格，因为软件的规模越大，协作性要求就越高，软件开发是一件群体性的智力活动，每个人的代码都只有自己懂，每段代码都将成为一个信息孤岛，没法让代码变得可交流、可复用、可维护。
2、一段代码的功能，不仅仅是完成一个任务，也是一种思想的传播，因此注释担当着传递信息的功能，要养成良好的注释习惯和明了易懂注释风格。
3、留白的艺术深受启发，既给代码空间留下了闲余，给视觉留下了美感，也给代码的阅读增添了节奏，更是给大脑腾出足够的思考空间。
2020-05-09 08:24:40
1. 今天文章中的 "留白", 和 "命名" 我倒是注意到了, 但是可能因为我目前写的 c++ 代码基本上都是不超过 50 行的练习文件, 所以注释这一点我没有注意到, 从现在开始注意.
2. 我觉得另一个重要的用法是把一些代码备注掉. 可能是为了 debug 方便(如果新代码错了, 换回旧代码, 程序还能运行), 也可能是为了以后功能拓展方便(直接把相关模块取消备注就能用了).
补充一条我前天刚学会的 code style:
All header files should have #define guards to prevent multiple inclusion. The format of the symbol name should be <PROJECT>_<PATH>_<FILE>_H_
2020-05-09 10:46:39
2020-05-09 09:29:38
2020-05-09 07:58:17
2020-07-01 20:30:00
2020-05-09 07:21:02
2020-05-13 12:47:43
2020-05-11 16:43:05
2020-05-10 19:27:06
2020-05-10 15:56:28
如果不行，那尽量写上规整周全的注释，帮助其他人维护。这是中策。
如果代码写得不行，注释也没有就太糟糕了。
2020-05-18 21:32:03
代码除了注释之外，我觉得会写log也比较重要，很多程序不仅仅是再运行前审查代码，还有就是出错时候返回来看代码，这时候你的code style和log里面的内容就为精确排查错误剩下一大笔时间！！！
2020-05-17 22:25:11
1. 函数参数也是变量，该怎么命名能够直观地知道这个变量是入参，而不是局部变量？
2. 匈牙利命名法：string str_value;不是更能表示该变量是个字符串吗？
3. member fucntion要注释的话，建议采用单行//……， 还是多行 /* @param …… @return…… */？
2020-05-13 11:01:46
2020-05-09 21:53:58
团队英文水平有限，试过直接用中文来命名一些业务上较难翻译成英文或翻译后较繁琐的概念，用作变量名和函数名，反而没那么纠结，代码review或接手一看就懂
2020-05-09 19:31:12
2020-05-09 08:45:24
2020-05-09 07:45:02
2021-02-28 23:17:43
注释里的TODO确实是非常重要，因为很多开发都是迭代式的，写在代码中也能保证以后能快速想起要做的关键事项，可以提升效率同时最重要的是尽早发现以及避免错误