THE ART
oF
READABLE CODE
（1-5）
目的
细节决定成败
Part 1
代码应当易于理解
比下面的代码好：
但很多时候这个选择会更艰难。例如，这段代码：
return index >= 0 ? params * 10 : params * 5;
它比下面这段要好些还是差些？
if (index >= 0) {
return params * 10;
} else {
return params * 5;
}
第一个版本更紧凑，但第二个版本更直白。
哪个标准更重要呢？
一般情况下，在写代码时你如何来选择？
KEY
代码的写法应当使别人
理解它所需的时间最小化
assert((!(k = foo(key))) || !k->IsObj());
理解起来要比两行代码花更多时间：
k = foo(key);
if (k != NULL) assert(!k->IsObj());
PART 2
把信息放到名字里
send deliver dispatch announce distribute routefind search extract locatestart launch create begin openmake create set up build generate comp
1. 选择专业的词
tmp retval foo，可以作为名字的一部分,但是
不要轻易直接使用
eg: tmp_file我们就可以知道这是个临时文件
2. 避免泛泛的名字
3. 用具体的名字代替抽象的名字
比如建立和使用一个特殊的本地数据库作为本地
日志输出，run_locally这个名字只表达了模糊的
操作位置，却无法表示具体的作用， use_local_database就比较合适了.
4.用前缀或后缀来给名字附带更多信息
delay_ms 表示了延迟的时间单位
- 在小的作用域里可以使用短的名字 .
- 首字母缩写要视意思的表达效果而定.
- BEManager是另人费解的，而FormatStr()
人们可能会理解它的意思
5. 决定名字的长度
6. 利用名字的格式来表达含义
比如google的规范：
类成员变量和普通变量一样，但必须以一条下划线结 尾，如offset_.
PART 3
不会误解的名字
例子：Filter()
假设你在写一段操作数据库结果的代码：
results = Database.all_objects.filter("year <= 2011")
结果现在包含哪些信息？
• 年份小于或等于2011的对象？
• 年份不小于或等于2011年的对象？
推荐用 min 和 max 来表示（包含）极限
命名极限最清楚的方式是在要限制的东西前加上
max_或者min_
总结
阅读你代码的人应该理解你的本意，并不会有其他的理解。
1. 不会误解的名字是最好的名字
2. 当要定义一个值的上限或下限时，
max_和min_是很好的前缀
对于包含的范围，first和 last 是好的选择。
对于包含 排除范围， begin 和 end 是最好的选择，
因为它们最常用。
3. 当为布尔值命名时，使用 is 和 has
当为布尔值命名时，使用 is 和 has 这样的词来明确
表示它是个布尔值，避免使用反义的词
（例如 disable_ssl ）
PART 4
审美
-
使用从审美角度让人愉悦的编码方式编写的代码可以使人更加容易理解。
- 试想一下，你编程的大部分时间都花在看代码上，浏览代码的速度越快，人们就越容易使用它。
Key:
1. 重新安排换行保持一致和紧凑。
2. 用方法整理不规则的东西。
3. 在需要时使用列对齐。
4. 选择一个有意义的顺序，始终一致的使用它。
5. 把声明按块组织起来。
6. 把代码分成段落。
7. 个人风格与一致性。
修改前
修改后
再举一个例子
1. 上面的代码没什么美感可言，有些行长的都换行了。
2. 也没什么一致的风格。
3. 这里最大的问题是有很多重复的串。
其中还有很多error,这个时候我们需要一个辅助方法。
这样不仅让代码更有美感，而且还有几个附带作用：
1.消除了大量重复代码，让代码变的紧凑。
2.让代码的重要部分变的直白（名字和错误字符串），更改过后一眼就能分辨。
3.添加新的测试将会简单。
PART 5
该写怎样的注释
KEY
注释的目的是帮助读者尽可能了解得跟作者一样多
什么不需要注释？
1.不要为那些从代码本身就能快速推断的事实写注释：
2.不要为了注释而注释
修改前（没什么意义）
修改后（至少要给出更多重要细节）
3.不要为不好的名字加注释，应该把名字改好
修改前
修改后
通常来讲，我们不需要“拐杖式注释”——试图粉饰可读性差的代码的注释。
写代码的人常常把这条规则表述为：
好代码 > 坏代码 +好注释。
怎么加注释？
1 . 为瑕疵写注释。
可以在代码需要改进或者未完成的时候编写注释
有几种标记在程序员中很流行：
TODO: 我还没处理的事情。
FIXME: 已知无法运行的代码。
HACK：对一个问题不得不采用的比较粗糙的解决方案。
XXX: 危险！这里有重要问题。
2 . 为常量加注释。
需要描述清楚它是什么或者为什么它是这个值的原因，因为以后调整
这个变量的人可能需要知道调整的规则，另外对一个高精度调整过的
值可能不应该大幅调整，诸如此类的原因。
3 . 站在读者上的立场上思考
- 预料内的提问。
- 意料外的问题。
- 在文件/类的级别上使用全局观注释解释所有部分是如何一起工作的。
- 用注释总结代码块，使读者不会迷失在细节中。
the-art-of-readable-code
By kangxiaojun
