Google 如何進行 Code Review - 4

一窺 Google 內部程式審核的指導原則 - Speed of Code Reviews

ta-ching chen

1 minute read

原文

Speed of Code Reviews (程式審核的速度)

Why Should Code Reviews Be Fast? (為什麼審核速度要快)

在 Google 我們優化開發團隊共同生產產品的速度,而不是優化個人開發程式的速度。

個人的開發速度很重要,但它不如整個團隊的開發速度 (velocity of the entire team) 那般重要。

當程式審核很慢時,會發生以下幾件事:

  • 團隊整體的速度下降

是的,沒有快速回應的個人 (individual) 的確完成自己所屬的工作。但同時也表示,對於團隊其他人來說重要的新功能與缺陷修復將會被延遲數天、數週甚至數月,只因為它們正在等待審核與再審核。

  • 開發人員開始抗議程式審查流程

若審核者每隔幾天才回應一次,但每次都要求對 CL 進行重大更改的話,那麼開發人員可能會感到非常沮喪與覺得困難,而這通常會演變成對評論者的「嚴格」程度的抱怨。 如果審核者請求相同的實質性更改 (且確實可以改善程式品質狀況),但在每次開發人員提交新的改動時都能快速反應的話,這些抱怨往往會消失。

大多數關於程式審查過程的抱怨,往往可以通過加快流程來解決。

  • 程式品質會受到影響

當審核評論很慢時,會造成開發者提交不完全盡如人意的 CL 的壓力越來越大 [1]。評論的越慢也會阻止他人進行程式清理 (cleanups)、重構 (refactorings)、甚至是對現有 CL 的進一步改進。

  • [1] 還記得前面所說的嗎? 沒有完美的程式只有最佳的程式!

How Fast Should Code Reviews Be? (那程式審核應該要多快)

如果你並沒有處於需要專注工作 (focused task) 中間時,那麼你應該在 CL 被提交後儘快進行審查。

回應程式審查最長的極限是一個工作日是 (意即隔天早上的第一件事)

若遵循以上指南,意味著一般的 CL 應該在一天內得到多輪審核 (如果必要的話)。

Google 如何進行 Code Review - 3

一窺 Google 內部程式審核的指導原則 - Navigating a CL in review

ta-ching chen

1 minute read

原文

Navigating a CL in review (審核中該如何在 CL 巡航)

Summary (總結)

現在你已經知道審核時要看些什麼,但怎樣才是審核分散在多個文件中的改動最有效的方法?

  1. 改動是否合理? 他是否有好的描述 (description)
  2. 優先看 CL 最重要的改動。它整體是否有完善的設計?
  3. 用合理的順序看 CL 剩餘的改動

Step One: Take a broad view of the change (用宏觀的角度來看待改動)

Look at the CL CL description and what the CL does in general.

查看 CL 描述以及它做什麼

該改動是否有意義、合理?如果在第一時間認為不應該發生這種變化,請立即說明為什麼不該這樣做的原因。 當拒絕類似這樣的更改時,向開發人員提供建議告訴他們應該怎麼做什麼也是一個好主意 [1]。

例如,你可以說「看起來你已經完成一些不錯的事情,謝謝! 但我們實際上正朝著刪除你正在修改的 FooWidget 系統的方向前進,所以現階段我們不想對它進行任何新的修改。 你覺得不如重構我們的新 BarWidget class 的主意如何?」

值得注意的是,審核者在委婉拒絕該 CL 的同時提供替代方案,而且仍然保持「禮貌」。這種禮貌是很重要,因為我們希望表明即使不同意也會相互保持尊重。

如果你有幾個 CL 裡頭包含你不想這樣做的改動時 (a few CLs that represent changes you don’t want to make), 你應該考慮重新開發團隊的開發過程,或發佈開發流程給外部貢獻者 (contributor) 知道,以便在任何 CL 被撰寫前有更多的溝通。 最好是在他們開始投入大量工作前説「不」,避免那些已經投入心血的工作現在必須被拋棄或徹底重寫。

  • [1] 提供替代方案讓對方知道該怎麼做,而非讓其自行獨自摸索。
suggestion

點出可能問題,告知替代方案或指點方向

Step Two: Examine the main parts of the CL (檢查 CL 主要的部分)

Find the file or files that are the “main” part of this CL.

找到 CL 最核心的部分的那些文件

Google 如何進行 Code Review - 2

一窺 Google 內部程式審核的指導原則 - What to look for in a code review

ta-ching chen

2 minute read

原文

What to look for in a code review (程式審核過程中要看些什麼?)

Design (設計)

程式審核裡最重要的一環是 CL 的整體設計

CL 內多個程式片段的改動之間的交互作用是否合理? 改動是屬於程式庫 (codebase) 還是函式庫 (library)? 此次改動是否能和系統其他部分很好地整合? 現在是加入該功能的適當時機嗎?

Functionality (功能性)

CL 是否真的有符合開發者意圖? 開發者的意圖對於使用者們是好的嗎? 這裡使用者通常係指終端使用者 (受到改動而影響)開發者(未來會用到該程式的人)雙方。

在大多數情況,我們會期望開發者徹底測試他們的 CL,並期望在接受審核時它能夠正常運作。但身為審核者你仍必須去思考可能的「極端案例 (edge cases)」、找出「併發問題 (concurrency problem)」、 嘗試「作為一個使用者去思考」,並且確保「在單純閱讀程式碼時沒有明顯的程式缺陷 (bug)」。

願意的話你也可以去親自去驗證 CL - 如果當改動會帶來直面使用者的影響 (user-facing impact) 時,比方說 UI 改動,驗證 CL 的變化便會是審核者在整個過程中最重要的事情。 單純閱讀程式碼有時很難體會它會如何影響使用者,面對如此的改動如果覺得不方便自己測試的話,可以要求開發者展示 (demo) 此次改動的功能性。

另外,審核功能性時格外重要的一點是,要注意 CL 中是否有「平行程式設計 (parallel programming)」的存在,並是否在理論上會造成 deadlocks 或 race conditions。 這類的問題較難透過執行程式來查覺,通常會需要有人 (開發者跟審核者) 一起仔細思考,確保該問題不會被引入程式庫內。

Note: 這也是不使用可能會造成 deadlocks 或 race conditions 的併發模型 (concurrency model) 很好的理由 - 它可能會讓程式審核或理解上造成困難。

Complexity (複雜性)

一個 CL 是否複雜到超過原本所必須的? 針對任何層級的 CL 請務必確認這幾點 - 單行程式是否過於複雜? 函式是否過於複雜? Class 是否過於複雜?

「複雜」通常代表著該程式很難快速被閱讀程式的人所理解

也意味著很有可能其他開發者在呼叫或修改這段程式時引入缺陷

其中就是一種複雜性便是「過度設計 (Over-engineering)」,開發者會讓程式過度通用化 (more generic) 超過它原本所需的,或是新增現在系統不需要用到的功能 [1]。 審核者對於必須非常警惕過度設計的發生。

鼓勵開發者解決他們現在需要解決的問題,而那些猜測未來可能會需要被解決的問題

可以在真正面臨到那些未來的問題時才解決它們,因屆時你才能更清晰看到問題的樣貌 (actual shape) 與需求。

  • [1] 個人認為和 Donald Knuth 說得「過早最佳化是萬惡的根源 (Premature optimization is the root of all evil)」有類似意思。 自己在開發過程中也常常落入相同窠臼,認為未來可能會需要所以現在先寫起來放。但更常見的狀況是,當實際面臨問題時,狀況可能和原先大相徑庭導致需要重寫。

Google 如何進行 Code Review - 1

一窺 Google 內部程式審核的指導原則 - The Standard of Code Review

ta-ching chen

1 minute read

前言

貢獻開源專案 Fission 時,不僅會被他人審核也常需要審核來自世界各地開發者的 PR,從中體會到不少身為一個軟體工程師、一個專案維護者該有的行為與談吐。 近期 Google 公佈其內部關於「如何進行程式審核」的指導原則, 快速瀏覽相關內容後真的是心有戚戚焉,要是能更早知道這些技巧就不會摸索這麼長的時間。

認為這麼棒的文章沒有讓更多人看到實在非常可惜,因此嘗試自己翻譯來分享給中文的開發者。 若有文句不通暢、翻譯錯誤、typo,還煩請多包涵與指教。(部分找不到適當中文翻譯之專業名詞會以原文呈現)

原文

The Standard of Code Review (程式審核準則)

Code review 主要目的在於確保 Google 的程式庫 (code base) 整體健康度隨著時間推移能有所改善。 而所有的審核工具與流程皆是因應這個目的而生。為達到前述目的,勢必需要做出一連串的權衡與取捨 (trade-offs)。

首先,開發者必須能夠在任務上取得進展,若不對程式庫進行任何提交的話,那程式庫永遠不會有任何改善。 此外若審核者 (reviewer) 讓任何提交變得難以進入程式庫的話,則開發者會把「做出改善」這件事本身視為沒有益處,並且未來不再做出任何改善 [1]。

另一方面,審核者必須確保每個 CL (changelist) 的品質,且不會讓程式庫健康狀況隨著時間推移而下降。 儘管每個小改動只會造成品質微幅下降,但隨著時間拉長逐漸累積後,最後終將變成壓垮整體品質的那根稻草。 而這通常是非常棘手的事情,尤其是當團隊面臨時間壓力時,會讓他們認為必須抄小徑才能夠達成原訂目標。

再者,審核者對他們正在審核的程式有所有權與責任 (ownership and responsibility),確保程式庫能夠維持一致、易於維護,以及其他寫於 What to look for in a code review 的準則。

從中我們得到一個作為我們預期在程式審核過程中出現的原則 (標準):

一般而言,只要更動 (CL) 有助於提昇程式庫整體品質的話,審核者就應該批准它

儘管它並非完美

這點也是位於其他程式審核原則之上最高級的原則。

當然在某些狀況下這個原則也是會受到限制。比方說,某個 CL 涵括審核者不希望出現在系統的功能時,此時儘管 CL 的改動設計非常良好,審核者依然可以拒絕批准它。

主要重點在於「並沒有所謂完美的程式,只有更佳的程式」

審核者不該要求開發者在批准程式前仔細清理、擦拭 CL 每個角落 [2]。 相反的,審核者應該在 CL 的完善與其所帶來更動的重要性間做出權衡。與其追求「完美」,身為審核者更應該追尋「持續性的進步(continuous improvement)」。 只要 CL 對整體系統能改善 「維護性 (maintainability)」、「可讀性 (readability)」、「理解性 (understandability)」的話,就不應該因為它不完美而延遲批准數天甚至數週。

審核者也要習慣於針對 CL 可以改善的地方留下審核評論 (review comment)。如果指出的改正不是非常重要的話,可以在前面加上 Nit: 讓開發者知道該改正是可以選擇性被忽略的 [3]。

Note: 這份文件並非嘗試去證明合併 CL 絕對會造成程式庫品質下降的問題。唯一會發生這種事的應該是在緊急情況 [4]。

  • [1] 原文使用 disincentivized,找到最接近的解釋是 「移除做某些事的益處,導致其他人不想再做」。
  • [2] 將程式碼清理到完全符合審核者標準
  • [3] Nit 全稱為 Nitpick,意指吹毛求疵、雞蛋裏挑骨頭。自己本身會使用 nitpick,比如以下範例
nitpick

利用 nitpick 告知不在風格指南上的小問題

  • [4] 因緊急狀況而合併不完全符合品質要求的 CL

一個工程師的閱讀書單

各種個人有興趣的領域書單

ta-ching chen

1 minute read

前言

自己還蠻喜歡看書,尤其入手電子閱讀器後更是欲罷不能,不必再受限於書本重量且可以隨時隨地看書。 目前 kobo 的中文書籍相對全面以及時常有特價,因此蠻推薦購買他們家的電子閱讀器。

以下會提到自己是如何選出適合的書籍以及個人推薦書單,歡迎參考與交流 :)

選書技巧

由於書中的知識經過一定程度的梳理,在吸收與內化上速度比起自己悶著頭摸索來的快速。但是

沒有方向的船,任何方向都是逆風

因此個人選書時有個習慣是從自身較為薄弱的領域出發,思考當下或未來遭遇到的難題。 等確定好議題後找出能補強該弱項的書籍。比方未來有創業打算,便會針對公司營運、商業模式設計、團隊成長下手。

另外還有幾個小技巧:

  1. 台灣有出版「中文翻譯」的作品,除去譯者本身翻譯功力不到位的問題,內容相較來說較為紮實
  2. amazon 英文評論可以幫助你快速篩選書籍,4 星以上且多人評論較佳
  3. 中國作者的書籍會建議現場翻閱內容,有些形式較接近於短篇文章卻寫成書。導致內容冗長、精闢要點卻很少
  4. 跑誠品。沒錯,跑一趟誠品快速翻閱正在推廣的書籍。看作者文筆與內容是否符合自己,再考慮要去哪個平台買 XD

書籍分類

以下是根據上述選書技巧所列書單,建議於網站試閱後決定是否購買。

金融、理財

個人內在