编写可读代码的艺术(The Art of Readable Code)

https://book.douban.com/subject/10797189/

（找到更有表现力的词）下面是一些例子，这些单词更有表现力，可能适合你的语境：（不过我觉得开头这些词也挺好的）

单词	更多选择
send	deliver,dispatch,announce,distribute,route
find	search,extract,locate,recover
start	launch,create,begin,open
make	create,setup,build,generate,compose,add,new

在这种情况下，使用更精确的名词可能会更有帮助。如果不把循环索引命名为(i,j,k), 另外一个选择是(club_i, member_i, user_i)这样，或者是使用缩写(ci, mi, ui). 循环索引名称为了视觉上的效果，可以在前面增加一个迭代对象首字母前缀。

（带单位的值）下表给出一些没有单位的函数参数以及带单位的版本

函数参数	带单位的参数
Start(int delay)	delay -> delay_secs
CreateCache(int size)	size -> size_mb
ThrottleDownload(float limit)	limit -> max_kpbs
Rotate(float angle)	angle -> degrees_cw

（给名字附带额外信息）这种给名字附带额外信息的技巧不仅限于单位。在对于这个变量存在危险或者意外的时候，你都应该采用它。例如，很多安全漏洞来源于没有意识到你的程序接收到的某些数据还没有处于安全状态。在这种情况下，你可能想要使用像untrustedUrl或者unsafeMessageBody这样的名字。在调用了清查不安全输入的函数后，得到的变量可以命名为trustedUrl或者是safeMessageBody. 下表给出更多需要给名字附上额外信息的例子。

情况	变量名	更好的名字
一个纯文本格式的密码，需要加密之后才能进一步使用	password	plaintext_password
一条用户提供的注释，需要转义之后才能用于显示	comment	unescaped_comment
已经转换为UTF-8格式的html字节	html	html_utf8
以"url方式编码"的输入数据	data	data_urlenc

但你不应该给程序中每个变量都加上这样的属性，如果有人误解了这个变量就很容易产生缺陷，尤其会产生像安全缺陷这样的可怕的结果，在这些地方这种技巧最有用武之地。基本上，如果这是一个需要理解的关键信息，那就把它放在名字里。

（利用名字的格式来传递含义）在Google C++编码规范中：使用CamelCase来表示类名；使用lower_separated来表示变量名；常量格式是kConstantName而不是CONSTANT_NAME, 后者是宏的形式；类成员变量使用_结尾。

推荐使用begin/end来表示包含/排除范围（闭开区间），而使用first/last来表示包含的范围（闭闭区间）

有集中标记在程序员中很流行：

标记	通常的含义
TODO	我还没有处理的事情
FIXME	已知无法运行的代码
HACK	对于一个问题不得不采用比较粗糙的解决方案
XXX	危险！这里有重要的事情

注释的目的是帮助读者了解作者在写代码时已经知道的那些事情。本章介绍了如何发现所有的并不那么明显的信息快并且把它们写下来。

• 什么地方不需要注释：
  • 能从代码本身迅速的推断的事实。
  • 用来粉饰烂代码（譬如蹩脚的函数名）的“拐杖式注释”（我们应该把代码改好）。
• 你应该记录下来的想法包括：
  • 为什么代码写成这样而不是那样的内在理由（“指导性批注”）。
  • 代码中的缺陷，通常使用像TODO或者XXX这样的标记。
  • 常量背后的故事，为什么是这个值。
• 站在读者的立场上思考：
  • 预料到代码中哪些部分会让读者说：“啊？”并且给它们加上注释。
  • 为普通读者意料之外的行为加上注释。
  • 在文件/类级别上使用“全局观”注释来解释所有的部分是如何一起工作的。
  • 用注释来总结代码块，使读者不致迷失在细节中。

如何把更多的信息装入更小的空间：

• 尽量精确地描述函数的行为。
• 在注释中用精心挑选的输入/输出例子做说明。
• 声明代码的高层次意图，而非明显细节。
• 用嵌入注释(如Function(* arg= * …) )来解释难以理解的函数参数。
• 使用含义丰富的词来使注释简洁。

当把一件复杂的事向别人解释时，那些小细节很容易就会让他们迷惑。把一个想法用“自然语言”解释是个很有价值的能力，因为这样其他知识没有你这么渊博的人才可以理解他。这需要把一个想法先精炼成重要的概念。这样做不仅帮助他人理解，也帮助你自己把这个想法想的更清晰。在你把代码展示给读者时，也应该使用同样的技巧。我们接受代码是你解释程序所做的事情的主要手段这一观点，所以代码应当用“自然语言”编写。

为什么重用库有这么大的好处？一个常被引用的统计结果是，一个平均水平的软件工程师每天写出10行可以放到最终产品中的代码。当程序员刚一听到这个，他们根本不敢相信：“10行代码，我一分钟就写出来了。”注意这里的关键词是最终产品中的。在一个成熟的库中，每一行代码都代表相当大量的设计，调试，重写，文档，优化和测试。任何经受了这样的达尔文进化过程一样的代码行就是很有价值的。这就是为什么重用库有这么大的好处。不仅节省时间，还少写了代码。

在编写测试用例时，不要怕名字太长或太繁琐。在你的整个代码库中不会调用这个函数，因此那些要避免使用长函数名的理由在这里并不适用。测试函数的名字的作用就像是注释。并且如果测试失败了，大部分测试框架会输出其断言失败的那个函数的名字，因此一个具有描述性的名字尤其有帮助。