编写可读代码的艺术

“软件开发的一个重要部分是要意识到你的代码以后将如何影响查看这些代码的人。两位作者 高屋建瓴，带你领略这一挑战的各个方面，并且使用有指导意义的例子来解释细节。” ——Michael Hunger，软件开发人员 细节决定成败，思路清晰、言简意赅的代码让程序员一目了然；而格式凌乱、拖沓冗长的代码 让程序员一头雾水。除了可以正确运行以外，优秀的代码必须具备良好的可读性，编写的代码 要使其他人能在最短的时间内理解才行。本书旨在强调代码对人的友好性和可读性。 本书关注编码的细节，总结了很多提高代码可读性的小技巧，看似都微不足道，但是对于整个 软件系统的开发而言，它们与宏观的架构决策、设计思想、指导原则同样重要。编码不仅仅只 是一种技术，也是一门艺术，编写可读性高的代码尤其如此。如果你要成为一位优秀的程序员， 要想开发出高质量的软件系统，必须从细处着手，做到内外兼修，本书将为你提供有效的指导。 主要内容： ■ 简化命名、注释和格式的方法，使每行代码都言简意赅。 ■ 梳理程序中的循环、逻辑和变量来减小复杂度并理清思路。 ■ 在函数级别解决问题，例如重新组织代码块，使其一次只做一件事。 ■ 编写有效的测试代码，使其全面而简洁，同时可读性更高。 The Art of Readable Code 软件开发/编程 B osw ell & Foucher Dustin Boswell毕业于加州理工大学，资深软件工程师，在Google就职多年，负责Web爬虫和程 序设计相关的工作。他专注于前端、后端，服务器架构、机器学习、大数据、系统和网站等技 术领域的研究和实践，经验十分丰富。他现在是MyLikes的软件工程师。 Trevor Foucher资深软件工程师和技术经理，先后在Microsoft和Google工作了数十年，在 Microsoft担任软件工程师、技术经理以及安全产品技术主管，在Google从事广告应用开发和搜 索基础结构研发相关的工作。 oreilly.com.cn 编写可读代码的艺术 编 写 可 读 代 码 的 艺 术 编写可读代码的艺术 著 此简体中文版仅限于在中华人民共和国境内（但不允许在中国香港、澳门特别行政区和中国台湾地区）销售发行 This Authorized Edition for sale only in the territory of People's Republic of China (excluding Hong Kong, Macao and Taiwan) O'Reilly Media, Inc.授权机械工业出版社出版 定价：59.00元 客服热线：(010) 88378991，88361066 购书热线：(010) 68326294，88379649，68995259 投稿热线：(010) 88379604 读者信箱：hzjsj@hzbook.com 华章网站：http://www.hzbook.com 网上购书：www.china-pub.com 9 ISBN 978-7-111-38544-8 7 8 7 1 1 1 3 8 5 4 4 8 机 械 工 业 出 版 社 Dustin Boswell & Trevor Foucher 著 尹哲 郑秀雯 译 编写可读代码的艺术 编写可读代码的艺术 Dustin Boswell & Trevor Foucher 著 尹哲 郑秀雯 译 机械工业出版社 O’Reilly Media, Inc.授权机械工业出版社出版 Beijing • Cambridge • Farnham • Köln • Sebastopol • Tokyo 图书在版编目（CIP）数据 编写可读代码的艺术/（美）鲍斯维尔（Boswell, D.），富歇（Foucher, T.）著； 尹哲，郑秀雯译. －北京：机械工业出版社，2012.7 （O’Reilly精品图书系列） 书名原文：The Art of Readable Code ISBN 978-7-111-38544-8 I. 编… II. ①鲍… ②富… ③尹… ④郑… III. 代码－程序设计 IV. TP311.11 中国版本图书馆CIP数据核字（2012）第109081号 北京市版权局著作权 合同 劳动合同范本免费下载装修合同范本免费下载租赁合同免费下载房屋买卖合同下载劳务合同范本下载 登记 图字：01-2011-1275号 ©2012 by O,Reilly Media, Inc. Simplified Chinese Edition, jointly published by O, Reilly Media, Inc. and China Machine Press, 2012. Authorized translation of the English edition, 2012 O,Reilly Media, Inc., the owner of all rights to publish and sell the same. All rights reserved including the rights of reproduction in whole or in part in any form. 英文原版由O,Reilly Media, Inc. 出版2012。 简体中文版由机械工业出版社出版 2012。英文原版的翻译得到O,Reilly Media, Inc.的授权。此简体中文 版的出版和销售得到出版权和销售权的所有者 —— O,Reilly Media, Inc.的许可。 版权所有，未得书面许可，本书的任何部分和全部不得以任何形式重制。 封底无防伪标均为盗版 本书法律顾问 北京市展达律师事务所 书 名/ 编写可读代码的艺术 书 号/ ISBN 978-7-111-38544-8 责任编辑/ 谢晓芳 封面设计/ Susan Thompson，张健 出版发行/ 机械工业出版社 地 址/ 北京市西城区百万庄大街22号（邮政编码100037） 印 刷/ 开 本/ 178毫米×233毫米 16开本 12印张 版 次/ 2012年7月第1版 2012年7月第1次印刷 定 价/ 59.00元（册） 凡购本书，如有缺页、倒页、脱页，由本社发行部调换 客服热线：(010) 88378991; 88361066 购书热线：(010) 68326294; 88379649; 68995259 投稿热线：(010) 88379604 读者信箱：hzjsj@hzbook.com O’Reilly Media, Inc.介绍 O’Reilly Media通过图书、杂志、在线服务、调查研究和会议等方式传播创新知识。自1978年 开始，O’Reilly一直都是前沿发展的见证者和推动者。超级极客们正在开创着未来，而我们关 注真正重要的技术趋势——通过放大那些“细微的信号”来刺激社会对新科技的应用。作为 技术社区中活跃的参与者，O’Reilly的发展充满了对创新的倡导、创造和发扬光大。 O’Reilly为软件开发人员带来革命性的“动物书”；创建第一个商业网站（GNN）；组织了 影响深远的开放源代码峰会，以至于开源软件运动以此命名；创立了Make杂志，从而成为 DIY革命的主要先锋；公司一如既往地通过多种形式缔结信息与人的纽带。O’Reilly的会议和 峰会集聚了众多超级极客和高瞻远瞩的商业领袖，共同描绘出开创新产业的革命性思想。作 为技术人士获取信息的选择，O’Reilly现在还将先锋专家的知识传递给普通的计算机用户。无 论是通过书籍出版，在线服务或者面授课程，每一项O’Reilly的产品都反映了公司不可动摇的 理念——信息是激发创新的力量。 业界评论 “O’Reilly Radar博客有口皆碑。” ——Wired “O’Reilly凭借一系列（真希望当初我也想到了）非凡想法建立了数百万美元的业务。” ——Business 2.0 “O’Reilly Conference是聚集关键思想领袖的绝对典范。” ——CRN “一本O’Reilly的书就代 表 关于同志近三年现实表现材料材料类招标技术评分表图表与交易pdf视力表打印pdf用图表说话 pdf 一个有用、有前途、需要学习的主题。” ——Irish Times “Tim是位特立独行的商人，他不光放眼于最长远、最广阔的视野并且切实地按照 Yogi Berra的建议去做了：‘如果你在路上遇到岔路口，走小路（岔路）。’回顾 过去Tim似乎每一次都选择了小路，而且有几次都是一闪即逝的机会，尽管大路也 不错。” ——Linux Journal 译者序 在做IT的公司里，尤其是软件开发部门，一般不会要求工程师衣着正式。在我工作过的 一些环境相对宽松的公司里，很多程序员的衣着连得体都算不上（搞笑的T恤、短裤、 拖鞋或者干脆不穿鞋）。我想，我本人也在这个行列里面。虽然我现在改行做软件开发 方面的咨询工作，但还是改不了这副德性。衣着体面的其中一个积极方面是它体现了对 周围人的尊重，以及对所从事工作的尊重。比如，那些研究市场的人要表现出对客户的 尊重。而大多数程序员基本上每天主要的工作就是和其他程序员打交道。那么这说明程 序员之间就不用互相尊重吗？而且也不用尊重自己的工作吗？ 程序员之间的互相尊重体现在他所写的代码中。他们对工作的尊重也体现在那里。 在《Clean Code》一书中Bob大叔认为在代码阅读过程中人们说脏话的频率是衡量代码 质量的唯一标准。这也是同样的道理。 这样，代码最重要的读者就不再是编译器、解释器或者电脑了，而是人。写出的代码能 让人快速理解、轻松维护、容易扩展的程序员才是专业的程序员。 当然，为了达到这些目的，仅有编写程序的礼节是不够的，还需要很多相关的知识。这 些知识既不属于编程技巧，也不属于算法设计，并且和单元测试或者测试驱动开发这些 话题也相对独立。这些知识往往只能在公司无人问津的编程规范中才有所提及。这是我 所见的仅把代码可读性作为主题的一本书，而且这本书写得很有趣！ 既然是“艺术”，难免会有观点上的多样性。译者本身作为程序员观点更加“极端”一 些。然而两位作者见多识广，轻易不会给出极端的建议，如“函数必须要小于10行”或 者“注释不可以用于解释代码在做什么而只能解释为什么这样做”等语句很少出现在本 书中。相反，作者给出目标以及判断的标准。 翻译书是件费时费力的事情，好在本书恰好涉及我感兴趣的话题。但翻译本书有一点点 自相矛盾的地方，因为书中相当的篇幅是在讲如何写出易读的英语。当然这里的“英 语”大多数的时候只是指“自然语言”，对于中文同样适用。但鉴于大多数编程语言都 是基于英语的（至少到目前为止），而且要求很多程序员用英语来注释，在这种情况下 努力学好英语也是必要的。 感谢机械工业出版社的各位编辑帮助我接触和完成这本书的翻译。这本译作基本上可以 说是在高铁和飞机上完成的（我此时正在新加坡飞往香港的飞机上）。因此家庭的支 持是非常重要的。尤其是我的妻子郑秀雯（是的，新加坡的海关人员也对她的名字感兴 趣），她是全书的审校者。还有我“上有的老人”和“下有的小孩”，他们给予我帮助 和关怀以及不断前进的动力。 尹哲 i 目录 前言 ............................................................................ 1 第1章 代码应当易于理解 .............................................. 5 是什么让代码变得“更好” .............................................................................................6 可读性基本定理.....................................................................................................................7 总是越小越好吗.....................................................................................................................7 理解代码所需的时间是否与其他目标有冲突 ...............................................................8 最难的部分 .............................................................................................................................8 第一部分 表面层次的改进 .................................................9 第2章 把信息装到名字里 .............................................11 选择专业的词 ...................................................................................................................... 12 避免像tmp和retval这样泛泛的名字 ............................................................................. 14 用具体的名字代替抽象的名字 ....................................................................................... 17 为名字附带更多信息 ......................................................................................................... 19 名字应该有多长.................................................................................................................. 22 利用名字的格式来传递含义 ........................................................................................... 24 总结 ........................................................................................................................................ 25 ii 目录 第3章 不会误解的名字 ............................................... 27 例子：Filter() ....................................................................................................................... 28 例子：Clip(text, length) ................................................................................................... 28 推荐用first和last来表示包含的范围 ............................................................................. 29 推荐用begin和end来表示包含/排除范围 ................................................................... 30 给布尔值命名 ...................................................................................................................... 30 与使用者的期望相匹配 .................................................................................................... 31 例子：如何权衡多个备选名字 ....................................................................................... 33 总结 ........................................................................................................................................ 34 第4章 审美 ................................................................ 36 为什么审美这么重要 ......................................................................................................... 37 重新安排换行来保持一致和紧凑 ................................................................................... 38 用方法来整理不规则的东西 ........................................................................................... 40 在需要时使用列对齐 ......................................................................................................... 41 选一个有意义的顺序，始终一致地使用它 ................................................................. 42 把声明按块组织起来 ......................................................................................................... 43 把代码分成“段落” ......................................................................................................... 44 个人风格与一致性 ............................................................................................................. 45 总结 ........................................................................................................................................ 46 第5章 该写什么样的注释 ............................................ 47 什么不需要注释.................................................................................................................. 49 记录你的思想 ...................................................................................................................... 52 站在读者的角度.................................................................................................................. 54 最后的思考——克服“作者心理阻滞” ..................................................................... 58 总结 ........................................................................................................................................ 59 第6章 写出言简意赅的注释 ........................................ 60 让注释保持紧凑.................................................................................................................. 61 避免使用不明确的代词 .................................................................................................... 61 润色粗糙的句子.................................................................................................................. 62 目录 iii 精确地描述函数的行为 .................................................................................................... 62 用输入/输出例子来说明特别的情况 ............................................................................. 63 声明代码的意图.................................................................................................................. 64 “具名函数参数”的注释 ................................................................................................ 64 采用信息含量高的词 ......................................................................................................... 65 总结 ........................................................................................................................................ 66 第二部分 简化循环和逻辑 ...............................................67 第7章 把控制流变得易读 ............................................ 69 条件语句中参数的顺序 .................................................................................................... 70 if/else语句块的顺序 .......................................................................................................... 71 ?:条件表达式（又名“三目运算符”） ....................................................................... 73 避免do/while循环 .............................................................................................................. 74 从函数中提前返回 ............................................................................................................. 76 臭名昭著的goto ................................................................................................................. 76 最小化嵌套 .......................................................................................................................... 77 你能理解执行的流程吗 .................................................................................................... 80 总结 ........................................................................................................................................ 81 第8章 拆分超长的表达式 ............................................ 82 用做解释的变量.................................................................................................................. 83 总结变量 ............................................................................................................................... 83 使用德摩根定理.................................................................................................................. 84 滥用短路逻辑 ...................................................................................................................... 84 例子：与复杂的逻辑战斗 ................................................................................................ 85 拆分巨大的语句.................................................................................................................. 87 另一个简化表达式的创意方法 ....................................................................................... 88 总结 ........................................................................................................................................ 89 第9章 变量与可读性 ................................................... 91 减少变量 ............................................................................................................................... 92 缩小变量的作用域 ............................................................................................................. 94 iv 目录 只写一次的变量更好 ....................................................................................................... 100 最后的例子 ........................................................................................................................ 101 总结 ...................................................................................................................................... 103 第三部分 重新组织代码 ................................................. 105 第10章 抽取不相关的子问题 .................................... 107 介绍性的例子：findClosestLocation() ....................................................................... 108 纯工具代码 ........................................................................................................................ 109 其他多用途代码................................................................................................................ 110 创建大量通用代码 ........................................................................................................... 112 项目专有的功能................................................................................................................ 112 简化已有接口 .................................................................................................................... 113 按需重塑接口 .................................................................................................................... 114 过犹不及 ............................................................................................................................. 115 总结 ...................................................................................................................................... 116 第11章 一次只做一件事 ............................................117 任务可以很小 .................................................................................................................... 119 从对象中抽取值................................................................................................................ 120 更大型的例子 .................................................................................................................... 124 总结 ...................................................................................................................................... 126 第12章 把想法变成代码 ........................................... 127 清楚地描述逻辑................................................................................................................ 128 了解函数库是有帮助的 .................................................................................................. 129 把这个方法应用于更大的问题 ..................................................................................... 130 总结 ...................................................................................................................................... 133 第13章 少写代码 ..................................................... 135 别费神实现那个功能——你不会需要它 .................................................................... 136 质疑和拆分你的需求 ....................................................................................................... 136 保持小代码库 .................................................................................................................... 138 目录 v 熟悉你周边的库................................................................................................................ 139 例子：使用Unix工具而非编写代码 ............................................................................ 140 总结 ...................................................................................................................................... 141 第四部分 精选话题 ....................................................... 143 第14章 测试与可读性 ............................................... 145 使测试易于阅读和维护 .................................................................................................. 146 这段测试什么地方不对 .................................................................................................. 146 使这个测试更可读 ........................................................................................................... 147 让错误消息具有可读性 .................................................................................................. 150 选择好的测试输入 ........................................................................................................... 152 为测试函数命名................................................................................................................ 154 那个测试有什么地方不对 .............................................................................................. 155 对测试较好的开发方式 .................................................................................................. 156 走得太远 ............................................................................................................................. 158 总结 ...................................................................................................................................... 158 第15章 设计并改进“分钟/小时计数器” ................... 160 问题 ...................................................................................................................................... 161 定义类接口 ........................................................................................................................ 161 尝试1：一个幼稚的 方案 气瓶 现场处置方案 .pdf气瓶 现场处置方案 .doc见习基地管理方案.doc关于群访事件的化解方案建筑工地扬尘治理专项方案下载 ................................................................................................ 164 尝试2：传送带设计方案 ................................................................................................ 166 尝试3：时间桶设计方案 ................................................................................................ 169 比较三种方案 .................................................................................................................... 173 总结 ...................................................................................................................................... 174 附录 深入阅读 ......................................................... 175 1 前言 我不知道。 有一天，已经很晚了…… 两周后…… 这段代码是做什么 的？谁写的代码？ 2 前言 我们曾经在非常成功的软件公司中和出色的工程师一起工作，然而我们所遇到的代码仍 有很大的改进空间。实际上，我们曾见到一些很难看的代码，你可能也见过。 但是当我们看到写得很漂亮的代码时，会很受启发。好代码会很明确告诉你它在做什 么。使用它会很有趣，并且会鼓励你把自己的代码写得更好。 本书旨在帮助你把代码写得更好。当我们说“代码”时，指的就是你在编辑器里面要写 的一行一行的代码。我们不会讨论项目的整体架构，或者所选择的设计模式。当然那 些很重要，但我们的经验是程序员的日常工作的大部分时间都花在一些“基本”的事情 上，像是给变量命名、写循环以及在函数级别解决问题。并且这其中很大的一部分是阅 读和编辑已有的代码。我们希望本书对你每天的编程工作有很多帮助，并且希望你把本 书推荐给你团队中的每个人。 本书内容安排 这是一本关于如何编写具有高可读性代码的书。本书的关键思想是代码应该写得容易理 解。确切地说，使别人用最短的时间理解你的代码。 本书解释了这种思想，并且用不同语言的大量例子来讲解，包括C++、P y t h o n、 JavaScript和Java。我们避免使用某种高级的语言特性，所以即使你不是对所有的语言都 了解，也能很容易看懂。（以我们的经验，反正可读性的大部分概念都是和语言不相关 的。） 每一章都会深入编程的某个方面来讨论如何使代码更容易理解。本书分成四部分： 表面层次上的改进 命名、注释以及审美——可以用于代码库每一行的小提示。 简化循环和逻辑 在程序中定义循环、逻辑和变量，从而使得代码更容易理解。 重新组织你的代码 在更高层次上组织大的代码块以及在功能层次上解决问题的方法。 精选话题 把"易于理解"的思想应用于测试以及大数据结构代码的例子。 如何阅读本书 我们希望本书读起来愉快而又轻松。我们希望大部分读者在一两周之内读完全书。 前言 3 章节是按照"难度"来排序的：基本的话题在前面，更高级的话题在后面。然而，每章都 是独立的。因此如果你想跳着读也可以。 代码示例的使用 本书旨在帮助你完成你的工作。一般来说，可以在程序和文档中使用