程序員的 README

克里斯·里科米尼（Chris Riccomini）：

软件工程师，创业公司投资者和顾问，在PayPal、领英和WePay等大型科技公司拥有超过十年的工作经验；在职业生涯中一直参与开源项目的工作，是Apache Samza的作者。

 

德米特里·里亚博伊（Dmitriy Ryaboy）：

软件工程师和工程经理；目前担任Zymergen公司的软件工程副总裁；曾就职于不同的公司和组织，包括劳伦斯伯克利国家实验室、Cloudera和Twitter；帮助创建和发展了多个开源项目，包括Apache Parquet。

 

 

第 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