正版 程序员的README

第 1 章 前面的旅程 1 1.1 你的目的地 1 1.2 你的旅程地图 2 1.2.1 新手营 3 1.2.2 试炼之河 5 1.2.3 贡献者之角 5 1.2.4 运维之海 6 1.2.5 胜任之湾 6 1.3 前进！ 7 第 2 章 步入自觉阶段 8 2.1 学习如何学习 9 2.1.1 前置学习 9 2.1.2 在实践中学习 9 2.1.3 运行实例代码 11 2.1.4 阅读 11 2.1.5 观看讲座 13 2.1.6 适度地参加会议和聚会 14 2.1.7 跟班学习并同有经验的工程师结对 15 2.1.8 用副业项目实践 16 2.2 提出问题 17 2.2.1 动手调查一下 17 2.2.2 设置一个时间 17 2.2.3 写下全过程 18 2.2.4 别打扰别人 19 2.2.5 多用“非打扰式”交流 20 2.2.6 批量处理你的同步请求 20 2.3 克服成长的障碍 21 2.3.1 冒充者综合征 21 2.3.2 邓宁-克鲁格效应 22 2.4 行为准则 23 2.5 升级加油站 23 第3 章 玩转代码 25 3.1 软件的熵 26 3.2 技术债 26 3.3 变更代码 29 3.3.1 善于利用现有代码 30 3.3.2 过手的代码要比之前更干净 32 3.3.3 做渐变式的修改 33 3.3.4 对重构要务实 33 3.3.5 善用IDE 34 3.3.6 请使用VCS 的很好实践 34 3.4 避“坑”指南 35 3.4.1 保守一些的技术选型 36 3.4.2 不要特立独行 39 3.4.3 不要只分叉而不向上游提交修改 40 3.4.4 克制重构的冲动 40 3.5 行为准则 42 3.6 升级加油站 42 第4 章 编写可维护的代码 44 4.1 防御式编程 45 4.1.1 避免空值 45 4.1.2 保持变量不可变 46 4.1.3 使用类型提示和静态类型检查器 46 4.1.4 验证输入 47 4.1.5 善用异常 49 4.1.6 异常要有准确含义 50 4.1.7 早抛晚捕 51 4.1.8 智能重试 52 4.1.9 构建幂等系统 53 4.1.10 及时释放资源 53 4.2 关于日志的使用 54 4.2.1 给日志分级 55 4.2.2 日志的原子性 56 4.2.3 关注日志性能 57 4.2.4 不要记录敏感数据 59 4.3 系统监控 59 4.3.1 使用标准的监控组件 60 4.3.2 测量一切 63 4.4 跟踪器 64 4.5 配置相关注意事项 64 4.5.1 配置无须新花样 65 4.5.2 记录并校验所有的配置 66 4.5.3 提供默认值 67 4.5.4 给配置分组 67 4.5.5 将配置视为代码 67 4.5.6 保持配置文件清爽 68 4.5.7 不要编辑已经部署的配置 68 4.6 工具集 68 4.7 行为准则 70 4.8 升级加油站 71 第5 章 依赖管理 72 5.1 依赖管理基础知识 73 5.1.1 语义化版本 74 5.1.2 传递依赖 75 5.2 相依性地狱 76 5.3 避免相依性地狱 80 5.3.1 隔离依赖项 80 5.3.2 按需添加依赖项 81 5.3.3 指定依赖项的版本 82 5.3.4 依赖范围最小化 84 5.3.5 保护自己免受循环依赖的影响 84 5.4 行为准则 85 5.5 升级加油站 85 第6 章 测试 87 6.1 测试的多种用途 87 6.2 测试类型 88 6.3 测试工具 91 6.3.1 模拟库 91 6.3.2 测试框架 92 6.3.3 代码质量工具 93 6.4 自己动手编写测试 95 6.4.1 编写干净的测试 95 6.4.2 避免过度测试 96 6.5 测试中的确定性 98 6.5.1 种子随机数生成器 99 6.5.2 不要在单元测试中调用远程系统 99 6.5.3 采用注入式时间戳 99 6.5.4 避免使用休眠和超时 102 6.5.5 记得关闭网络套接字和文件句柄 102 6.5.6 绑定到0 端口 103 6.5.7 生成专享的文件路径和数据库位置 103 6.5.8 隔离并清理剩余的测试状态 103 6.5.9 不要依赖测试顺序 104 6.6 行为准则 105 6.7 升级加油站 105 第7 章 代码评审 107 7.1 为什么需要评审代码 107 7.2 当你的代码被评审时 109 7.2.1 准备工作 109 7.2.2 用评审草案降低风险 110 7.2.3 提交评审请勿触发测试 111 7.2.4 预排大体量的代码修改 111 7.2.5 不要太在意 112 7.2.6 保持同理心，但不要容忍粗鲁 113 7.2.7 保持主动 113 7.3 评审别人的代码时 114 7.3.1 分流评审请求 114 7.3.2 给评审预留时间 114 7.3.3 理解修改的意图 115 7.3.4 提供全面的反馈 115 7.3.5 要承认优点 116 7.3.6 区分问题、建议和挑剔 116 7.3.7 不要只做橡皮图章 117 7.3.8 不要只局限于使用网页版的评审工具 118 7.3.9 不要忘记评审测试代码 118 7.3.10 推动决断 118 7.4 行为准则 119 7.5 升级加油站 120 第8 章 软件交付 121 8.1 软件交付流程 121 8.2 分支策略 122 8.3 构建环节 125 8.3.1 打包需要带版本号 126 8.3.2 将不同的资源单独打包 127 8.4 发布环节 129 8.4.1 请勿只想着发布 129 8.4.2 将包发布到仓库 130 8.4.3 保持版本不变性 131 8.4.4 频繁发布 131 8.4.5 对发布计划保持透明 132 8.4.6 撰写变更日志和发行说明 132 8.5 部署环节 133 8.5.1 自动部署 133 8.5.2 部署的原子性 134 8.5.3 独立地部署应用 134 8.6 展开环节 136 8.6.1 系统监控 137 8.6.2 特性开关 137 8.6.3 熔断器 138 8.6.4 并行的服务版本梯队 139 8.6.5 摸黑启动 141 8.7 行为准则 143 8.8 升级加油站 144 第9 章 On-Call 146 9.1 On-Call 的工作方式 147 9.2 On-Call 技能包 148 9.2.1 随时响应 148 9.2.2 保持专注 148 9.2.3 确定工作优先级 149 9.2.4 清晰的沟通 150 9.2.5 跟踪你的工作 151 9.3 事故处理 152 9.3.1 分流 153 9.3.2 协同 154 9.3.3 应急方案 155 9.3.4 解决方案 157 9.3.5 后续行动 159 9.4 提供支持 162 9.5 不要逞英雄 164 9.6 行为准则 165 9.7 升级加油站 165 第 10 章 技术设计流程 167 10.1 技术设计的V 形结构 168 10.2 关于设计的思考 169 10.2.1 定义问题 170 10.2.2 着手调查 171 10.2.3 进行实验 172 10.2.4 给些时间 173 10.3 撰写设计文档 174 10.3.1 文档持续变更 174 10.3.2 了解撰写文档的目的 175 10.3.3 学会写作 176 10.3.4 保证文档是近期新的 176 10.4 使用设计文档模板 177 10.4.1 概要 178 10.4.2 现状与背景 178 10.4.3 变更的目的 178 10.4.4 需求 179 10.4.5 潜在的解决方案 179 10.4.6 建议的解决方案 180 10.4.7 设计与架构 180 10.4.8 测试计划 181 10.4.9 发布计划 181 10.4.10 遗留的问题 181 10.4.11 附录 181 10.5 协作设计 182 10.5.1 理解你的团队的设计评审流程 182 10.5.2 不要让人惊讶 183 10.5.3 用设计讨论来进行头脑风暴 183 10.5.4 为设计出力 184 10.6 行为准则 185 10.7 升级加油站 185 第 11 章 构建可演进的架构 187 11.1 理解复杂性 188 11.2 可演进的设计 189 11.2.1 你不是真的需要 189 11.2.2 最小惊讶原则 191 11.2.3 封装专业领域知识 193 11.3 可演进的API 193 11.3.1 保持API 小巧 194 11.3.2 公开定义良好的服务端API 194 11.3.3 保持API 变更的兼容性 195 11.3.4 API 版本化 198 11.4 可持续的数据管理 199 11.4.1 数据库隔离 199 11.4.2 使用schema 201 11.4.3 schema 自动化迁移 203 11.4.4 保持schema 的兼容性 206 11.5 行为准则 207 11.6 升级加油站 208 第 12 章 敏捷计划 210 12.1 敏捷宣言 210 12.2 敏捷计划的框架 211 12.3 Scrum 框架 212 12.3.1 用户故事 213 12.3.2 任务分解 214 12.3.3 故事点 214 12.3.4 消化积压 216 12.3.5 冲刺计划 216 12.4 站会 217 12.5 评审机制 218 12.6 回顾会 219 12.7 路线图 220 12.8 行为准则 221 12.9 升级加油站 222 第 13 章 与管理者合作 223 13.1 管理者是做什么的 223 13.2 沟通、目标与成长 224 13.2.1 一对一面谈 225 13.2.2 PPP 227 13.2.3 OKR 229 13.2.4 绩效考核 230 13.3 向上管理 232 13.3.1 接收反馈 232 13.3.2 给予反馈 233 13.3.3 讨论你的目标 235 13.3.4 事情不顺时要采取行动 236 13.4 行为准则 238 13.5 升级加油站 239 第 14 章 职业生涯规划 241 14.1 迈向资深之路 241 14.2 职业生涯建议 242 14.2.1 T 型人才 242 14.2.2 参加工程师训练营 243 14.2.3 主导你自己的晋升 244 14.2.4 换工作需谨慎 246 14.2.5 自我调节 247 14.3 结尾寄语 248

克里斯·里科米尼（Chris Riccomini）： 软件工程师，创业公司投资者和顾问，在PayPal、领英和WePay等大型科技公司拥有超过十年的工作经验；在职业生涯中一直参与开源项目的工作，是Apache Samza的作者。 德米特里·里亚博伊（Dmitriy Ryaboy）： 软件工程师和工程经理；目前担任Zymergen公司的软件工程副总裁；曾就职于不同的公司和组织，包括劳伦斯伯克利国家实验室、Cloudera和Twitter；帮助创建和发展了多个开源项目，包括Apache Parquet。

【摘自推荐序】 在本书的前几章中，“提问”就被高度重视，这让我感到非常高兴。向同事提问和学习是快速成长和习得新技能的有效方式。为你的工作成果感到自豪通常是件好事，但当自己在持续改进和交付中比以前做得更好时，你应该优先感到自豪。 这本书针对如何改进、如何学习、如何推进职业生涯发展，以及如何成为一名更好的开发者提供不同的方法和步骤。这本书包含适应团队的工作流程、处理会议、如期交付、善用学习工具和技术领域的best实践，并指导人们如何成为团队中有价值的成员。 向资深工程师寻求帮助可能会让人感到一丝畏惧，因为打断他们的工作通常是不妥的。资深工程师往往在聚精会神工作时会因为被打扰而失去在脑海中已构建的系统的短期记忆，但大多数资深工程师都很愿意提供帮助，优秀的资深工程师更是以指导和协助他人为荣。如果你在寻求帮助时感受到了敌意，大可不必心烦意乱，因为这在每个人身上都可能发生。不要让某一次糟糕的遭遇阻断了你再次寻求帮助的欲望。但总是打断他人的工作并非是合适的，这时就可以使用这本书中涵盖的其他策略和原则，它们都可以指导你将职业生涯提升到新的阶段。 无论你处于职业生涯的哪个阶段，这本书都非常实用。请保持开放的心态，好学深思，渴望提高，不惧破旧习，不惧提问题。 ——雅克·奥洛夫松（Jerker Olofsson），索尼移动公司前核心架构师 【摘自译者序】 本书的两位作者在最后一章中说：“你可以为任何行业做出贡献，从科学到农业、健康、娱乐，甚至是太空探索。”我一直都认为软件工程师的工作带来的成就感并不亚于小说家、建筑师或音乐家。软件开发本身带来的欣喜是一种“尤里卡时刻”的幸福体验，尤其是在无数个面对调试器“狂按”F10 键的夜晚，自己提交的特性成功上线时的喜悦，抑或是眼看着自己设计的技术架构方案从纸面上的框图到代码实现再到最终交付的满足感。 当然在软件行业工作也有艰辛，变动的需求、阻滞的沟通、糟糕的管理和紧迫的工期，总有些时刻会令人产生倦怠。毕竟真实世界中并不存在只和机器进行沟通的工作，更多的还是人与人之间的交流。本书能够很好地帮助刚刚踏入这个行业的工程师去认识真实世界。似乎从来都是程序员为他人撰写README，从来没有人为程序员撰写过README。 由于工作的关系，我个人不仅参与过采用瀑布流模型的传统项目，也参与过靠前灵活多变的研发项目，以及采用改良后的Scrum 框架的敏捷项目。虽然各自采用的开发模型不尽相同，但是遇到的问题都很相似。在实际的工作中，成功地交付软件并不是只有专享的路径可走。如何衡量与之匹配的需求、成本和风险才是考验团队的地方。本书中，两位作者提到了软件开发过程中的诸多困境，在我曾经的工作中也遇到过类似的情况。至今我还记得曾经有一次由于共享的数据层竞合而引发的生产环境故障，整个团队高负荷地工作了一周才最终解决。而在应对这起故障的过程中，团队明明在非常积极地处理，却引起了客户的极大不满。让客户不满的并不是故障本身，而是出了故障之后得不到应急方案导致了长时间的服务器宕机。如果那个时候能采用本书中提到的事故处理的标准流程（分流、协同、应急方案、解决方案和后续行动），那么很多弯路就可以避免了。 ——付裕，本书译者

对于刚刚成为软件工程师的新手来说，知道如何编写代码只是成功了一半。你可能很快就会发现，学校并没有教授在现实世界中至关重要的技能和工作中必要的流程。本书恰恰填补了这一环节，它是作者十多年来在大型公司指导初级工程师工作的教程，涵盖软件工程的基础知识和best实践。 本书第1～2 章讲解当你在公司开启你的职业生涯时会发生什么；第3～11 章会扩展你的工作技能，教你如何使用现有代码库、解决和防止技术债、编写生产级软件、管理依赖关系、有效地测试、评审代码、交付软件、处理On-Call 时的事故和构建可演进的架构等；剩余章节涵盖管理能力和职业阶梯的提升等相关内容，例如敏捷计划、与管理者合作以及成长为资深工程师的必经之路。本书中非常重要的一部分内容是教你如何应对糟糕的管理，以及如何调整自己的节奏。 本书内容不仅浅显易懂，还覆盖整个软件开发周期，是一本技术主管希望每名新入行的工程师在开始工作之前都能阅读的书。

（1）这是一本 “课外”书。知道如何编写代码，仅仅是“战斗的一半”。像与资深导师喝咖啡一样，本书将教授你学校里计算机课没有涉及的技能。 （2）这是一本有态度的书。公司之间总有差异，基本原理总是相通。书中构建团队的经验取自那些快速成长的、由风险投资公司资助的或者准上市的硅谷公司。 （3）这是一张进军职场“线路图”。资深之路选择多，请主导你自己的晋升。本书涵盖构建、测试和运行生产软件的现代实践，使团队更强大和使队友更默契的行为和多种方法，供你选择。 （4）作者是Zymergen 的软件工程副总裁和Apache Samza的作者，在 PayPal、LinkedIn、WePay 和 Twitter等主要科技公司拥有十多年的经验。