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

書籍分類

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

金融、理財

個人內在

Fission 1.4 更新重點聚光燈

你知道 Fission 能夠部署 Tensorflow ML 模型了嗎 ?

ta-ching chen

2 minute read

Introduction

在近兩個月的時間裡,針對來自不同用戶的反饋及問題回報 (包含前陣子的通靈故事 Localhost 迷航記), 我們在 1.4.0 與 1.4.1 做出許多值得一提的改變,讓 Fission 能更加適應跑在不同生產環境上。就讓我們來看看多了什麼改變吧!

Highlight

新的實驗環境: Tensorflow Serving

Tensorflow 作為被廣泛接納的機器學習框架,許多公司會利用它來訓練自家模型。但常會發生:

  1. 工程師懂得寫跟訓練模型,卻沒有相關部署知識
  2. 需要花額外時間撰寫 RESTful API server 來服務請求

因此「如何將機器學習模型快速部署到生產環境上」,一直是許多人心中的痛。

有鑑於此 Tensorflow 官方推出 (Tensorflow) Serving 試圖降低模型產出到部署之間的難度。 只要將模型放到對應資料夾內,Serving 偵測到模型後便會啟動對應 API server 服務,甚至版本異動時亦會將請求流量逐步轉移至新的模型。

然而,實際營運上考慮的因素絕不單單只有「將模型利用 API server 來服務預測請求」這麼簡單。

更多數情況我們會問的是:

如何大規模部署機器學習模型? (How to deploy ML models at scale?)

這個問題就牽涉到「底層架構」與「服務水平伸縮」等等議題。