Google 如何進行 Code Review - 5

一窺 Google 內部程式審核的指導原則 - How to write code review comments

ta-ching chen

1 minute read

 文章目錄

原文 

How to write code review comments (如何寫審核評論) 

Summary (總結) 

  • 和藹且有禮貌的
  • 解釋你的理由
  • 在「給出明確的方向 (explicit directions) 」與「只點出問題點，讓開發者做決定」之間作出權衡
  • 鼓勵開發者簡化程式或增加註釋，而非向你解釋這問題有多複雜

Courtesy (禮貌) 

一般而言，對你正在審查其程式的開發人員來說，保持禮貌與尊重的同時，確保評論是非常清楚和有幫助。

一種方法是確保

永遠對程式碼發表評論，而永遠不要對開發人員發表評論

你可能並不總是必須遵循這種做法，但你絕對要在說出會使人不安或有爭議的事情時使用這種方法。例如:

  • 糟糕的例子:

Why did you use threads here when there’s obviously no benefit to be gained from concurrency?

為什麼**「你」**要在使用併發沒有明顯益處時使用 threads?

  • 好的例子

The concurrency model here is adding complexity to the system without any actual performance benefit that I can see. Because there’s no performance benefit, it’s best for this code to be single-threaded instead of using multiple threads.

在我看來，這裡使用併發模型會增加整體系統的複雜性，卻沒有帶來任何實際性能效益。由於沒有性能上的效益，我們最好在這個程式裡使用 single-threaded 而非 multiple threads。[1]

  • [1] 工程師有個常犯的錯誤:「用極度效率的語言來解決事情，卻忽略可能帶來後續潛在的問題」。 前面兩個例子中，第一種方式雖然能用簡短一句話來作結，但會讓對方心生不滿認為是在譴責自己。 第二種方式雖然冗長，卻能讓對方理解到評論是針對「程式」而非「人」，避免未來團隊氣氛不佳或衝突。 記住，有時候「慢慢來比較快」

Explain Why (說明原因) 

從上面的「好」的例子中，你會注意到的一件事是「說明原因可以幫助開發者理解你為什麼發表評論」。 儘管你並不總是需要在評論中包含此訊息，但有時候提供更多解釋對於你的意圖、正在遵循的最佳做法、提供的建議如何提高程式品質，會是十分有幫助的。

Giving Guidance (提供引導) 

一般來說修繕 CL 是開發者的責任，而非審核者的

你不需要為此為某個解決方案去進行詳細的設計或寫程式給開發者。

然而這並不意味著審核者是沒有任何幫助，你應該在指出問題與提供直接指導之間取得適當的平衡。 指出問題並讓開發人員做出決定通常有助於他們學習，並使得未來程式審查變得更容易。 同時間還有可能產生出更好的解決方案，因為開發人員可能比你更接近、瞭解程式的樣貌。 但有時直接給予明確的方向、建議甚至程式也是相當有用的。

記住程式審查的主要目的在於:

  1. 得到最佳 CL
  2. 提高開發人員的技能。以便隨著時間的推移，他們需要的審查會越來越少

Accepting Explanations (接受說明) 

如果您要求開發人員去解釋一段你無法理解的程式時，那通常會讓他們嘗試更清楚地重寫它。偶爾，在程式中添加註釋也是一種恰當作法，只要它不是用來解釋過於複雜的程式 [1]。

僅在程式審查工具中留下的註釋，對後來的讀者來說沒有任何幫助

這在少數情況下是可接受的。例如當你在審核某個不熟悉的領域時，開發人員會在工具中編寫註釋來解釋的普通程式讀者已經知道的內容。

  • [1] 此處應該是指註釋雖然有用，但面對過於複雜的程式還盡量用重構來取代

下篇: Handling Pushback in Code Reviews

相關文章

文章內容的轉載、重製、發佈，請註明出處: https://tachingchen.com/tw/
comments powered by Disqus