Skip to content

Latest commit

 

History

History
42 lines (26 loc) · 3.94 KB

google_code_review_1.md

File metadata and controls

42 lines (26 loc) · 3.94 KB

Ref

Google 如何進行 Code Review - 1

程式碼審核準則

  • 一般而言,只要更動有助於提升程式庫的整體品質,審核者就應該批准,儘管它並非完美 - 最高級原則

    • 當然在某些狀況下這個原則也是會受到限制。比方說,某個 CL 涵括審核者不希望出現在系統的功能時,此時儘管 CL 的改動設計非常良好,審核者依然可以拒絕批准它。
  • 審核者須確保每個 changelist(CL) 的品質,且不會讓程式庫健康狀況隨著時間推移而下降

    • 儘管每個小改動只會造成品質微幅下降,但隨著時間拉長逐漸累積,最後終將變成壓垮整體品質的那根稻草,這通常是非常棘手的事情,尤其是當團隊面臨時間壓力,會讓他們認為抄小徑才能夠達成原定目標
  • 審核者應該在 CL 的完善與其所帶來更動的重要性之間作出權衡,與其追求完美,身為審核者更應該追尋 持續性的進步 ,只要 CL 對整體系統能改善

    • 維護性(maintainability)
    • 可讀性(readability)
    • 理解性(understandability) 就不該因為他不完美而延遲批准數天甚至數週
  • 如果指出的改正不是非常重要的話,可以前面加 Nit: 讓開發者知道該改正是可以選擇性被忽略的 (Nit = Nitpick 意指吹毛求疵、雞蛋裡挑骨頭)

Mentoring - 指導

  • 程式審核在教導開發者新的東西如程式語言、框架、通用軟體開發原則時扮演非常重要的角色。適時的留下評論來協助他人學會新東西永遠是件好事, 分享知識亦會讓整體程式品質隨著時間推移下得到提昇。

Principles - 原則

  • 以技術事實與資料 (數據) 為根本,否決意見與個人偏好
  • 關於程式風格的問題,風格指南 是絕對的。任何沒有列在其上的風格要點 (如空格等等) 則關乎每個人的個人喜好。一般來說,風格要和已經存在的程式保持一致。如果原先不存在任何風格的話,則接受 CL 作者的。
  • 任何有關「軟體設計 (software design)」的層面,從來都不單純是風格或個人喜好的問題。軟體設計必須要建立在基礎原則之上,並且在眾多原則間做出權衡,而不該僅是個人意見。 有時候若有數個不同的可行方案,只要作者能夠展示 (根據數據或完善的工程原則) 這些方案彼此是相等的 (equally valid),審核者則應該接受作者的選擇。 否則,設計方案的選擇則應該追尋軟體設計的標準原則來進行。
  • 如果沒有其他規則適用的話,則審核者可以要求作者和現有的程式庫保持一致風格,只要這樣不會讓整體系統程式的品質惡化的話。

Resolving Conflicts - 解決衝突

在任何衝突發生時,第一步永遠是開發者與審核者雙方根據此份及其他在「CL 作者指南」 以及「審核者指南」的文件來嘗試達成共識。

如果達成共識變得尤其困難時,雙方來個面對面會議 (face-to-face meeting) 或視訊會議 (VC) 或許會有所幫助,而不要僅依靠透過評論來試著解決衝突 [1]。 (如果選擇採用 face-to-face meeting & VC,請確保將最後結論記錄在 CL 的評論裡,以便後人查閱。)

如果上述做法仍無法解決衝突的話,最常見的作法是拉高處理問題的層級。從原先的兩人討論變成團隊討論、團隊領導 (TL) 來權衡 (weight in)、 讓程式維護者 (maintainer) 來決定,又或者由工程經理 (Eng Manager) 介入處理。

千萬不要讓改動因為作者跟審核者間無法達成共識而停留在那邊

純文字有時效率緩慢且容易造成誤解對方的情緒,透過對談方能快速理解與同步彼此的想法。 這種狀況對於遠端工作的團隊尤其重要,自己遇到類似情形會直接開視訊會議跟對方討論,確保彼此想法一致 (on the same page)。