市面上軟件開發流程方面的書可以說是數不勝數。我們無意在此做過多深入的討論,只想提幾點和溝通特別有關的,無論遵循何種開發理念,這些要點都值得關注。
### 代碼注釋
代碼注釋風格是一樣很主觀的東西。原作者常常通過詳細的注釋解釋自己的意圖和理由,這些對理解代碼都很有幫助,但是卻要付出后續維護的代價:過時甚至不準確的注釋反而會極大地妨礙對代碼的理解。同樣,過于扼要的注釋,或者干脆沒有注釋也會浪費將來維護或者API用戶的時間。注釋一般是用來說明代碼里缺失的部分,以及起得不好的名字,然后把代碼的功能再解釋一遍。注釋應該盡量解釋為什么代碼要那么寫,而不是去解釋代碼做了什么。
注釋在函數(或者方法)層面是最有用的,特別是用作API文檔的時候。注釋不應該涉及過多細節,用一句著名的希臘諺語來總結就是“μηδε?ν α?γαν”,即“過猶不及”。此外還應該好好為團隊準備一套注釋風格,然后每個人都要好好遵守——我們認為風格一致比風格本身更重要 <sup>1</sup> 。風格指南還應該自陳存在的理由及其目的——例如,這里是Google C++風格指南的介紹部分 <sup>2</sup> 。
C++是很多Google開源項目的主力開發語言。每個C++程序員都知道這門語言擁有多少強大特性,然而伴隨這種強大特性的是它的復雜性,這也使得代碼更容易出現 bug,難以閱讀和維護。
本文的目標是通過講解C++編程中的各種要點來駕馭這種復雜度。這些規則在保證代碼可控性的前提下,能讓程序員高效地使用C++的語言特性。
所謂的風格(也就是可讀性),就是管理 C++代碼的約定慣例。風格這個詞本身有點不恰當,因為這些約定所涵蓋的內容遠遠不止源文件格式化那么簡單。
強制統一代碼的風格是保持代碼可控的一種方法。讓別人快速看懂、理解代碼是非常重要的。保持一致的風格并遵守約定意味著可以簡單地通過“模式匹配”的方式來推斷各種符號的含義以及它們具有哪些不變的特性等信息。通用和強制要求的習慣和模式可以幫助理解代碼。有時候可能有很好的理由去改變某些風格,但是為了保證一致性,我們仍然會予以拒絕。
這份指南要解決的另一個問題是 C++的特性膨脹。C++博大精深,擁有很多高級特性。有時候我們需要限制(甚至禁止)使用某些特性,這是為了保持代碼簡潔,避免這些特性帶來的各種常見錯誤和問題。本指南會列出這些特性,并一一解釋為什么要限制它們。
Google的開源項目都遵守這份指南的規定。
注意本指南并非C++教程,我們假定讀者對這門語言已經有了相當的了解。
在源文件里署名(也就是“作者標簽欄”問題)
每個人都希望自己的工作得到認可,藝術家會在自己的畫作上簽名,文字工作者會把自己的名字放在書脊上或是博客頂部。無論以何種方式,渴望得到認可是人的本性,但是在我們看來,在源文件里留下名字絕對是弊大于利。你一定在各種源文件的頂部見過這樣的東西,它們往往和版權聲明擠在一塊兒。
~~~
# -------------------------------------------------
# Created: October 1998 by Brian W. Fitzpatrick <fitz@red-bean.com>
# -------------------------------------------------
~~~
在源代碼頂部署名的傳統已經是老黃歷了(我們兩個都這么干過,唉!),在程序大多由個人而非團隊編寫的年代這樣做或許還說得過去。但是今天,很多人只是接觸到一小塊代碼而已,文件里的作者標簽欄只會導致爭吵不休,浪費時間,甚至傷害感情。因此,我們強烈反對在源文件里署名的做法(最多也就是署上審核人的名字,告訴大家在修改這個文件后首先應該拿去給誰看,但是要小心不要有文件歸屬的暗示)。
想象一下,假如你在團隊項目里新建了一個文件——編寫了幾百行代碼,然后在文件頂部打上自己的名字和適當的版權信息,把它送去代碼審查,然后提交給代碼倉庫。到目前為止一切正常。現在假設你的同事阿德里安跑過來修改了一下文件,那么他要改多少才有資格把自己的名字寫上去呢?一定要修復一個bug以后?還是至少要五個bug?一定要實現一個函數?還是需要兩個函數?要寫多少行代碼才夠呢?如果他寫了一個函數,然后在文件上加上自己的名字,結果這個函數又被后來的人重寫了呢?這個人能不能也把她的名字加上去?是不是要把阿德里安的名字拿下來?和其他聯合創作(比如劇作、小說、電影等)不同,軟件即使在“完成”后依然會不斷發生變化。因此電影可以在結尾放心地列出創作人員,可在源文件上這樣添加、刪除名字的做法卻是一件永無止境的瘋狂舉動。
你當然可以通過大量文檔來解決這些問題,但是維護、跟蹤、防止意外發生都要浪費很多時間——這些時間原本都可以用來寫代碼的。因此我們推薦在項目層面而不是代碼上認可大家的工作。如果需要更多的細節,可以在版本控制系統里找到答案。一切都會隨時間散去,就像雨中的淚滴 <sup>3</sup> 。

追求個人“地盤”是很容易犯的錯
### 每個提交都必須經過代碼審查
如果打算要實行某種編程標準,那么就必須要有監控哪些代碼可以成為產品一部分的方法。無論是在提交之前還是之后進行代碼審查,都應該保證每一行進入倉庫的代碼都要有作者之外的人檢查過,檢查的內容有風格、質量,當然還有粗心大意的錯誤。代碼改動應該盡量短小以保證審查的質量——若改動涉及幾千行代碼,那么除了挑挑格式的毛病外,基本是沒辦法進行審查的。做到這一點不但能提高整個代碼庫的品質,更能從長遠上培養代碼質量的集體榮譽感。
### 真正的測試和發布流程
無論你是采用全套的測試驅動開發模式還是只有一些簡單的回歸測試,自動化程度越高,你在修復bug和添加新特性的時候就越自信。決定好測試所要扮演的角色后,它在編程和審查階段都應該占有一席之地。發布流程也是一樣重要,它應該方便到可以頻繁發布的程度(比如每周一次),同時也要具備相當的完備性,這樣才能在用戶之前發現問題。
* * * * *
> <sup>1</sup> 達斯汀·伯斯維爾和特拉佛·佛切爾在《編寫可讀代碼的藝術》一書中對注釋有一節精彩的論述。
> <sup>2</sup> 本文以及其他風格指南可以在這里找到:http://code.google.com/p/google-style-guide/。
> <sup>3</sup> 這是1982年的電影《銀翼殺手》里羅伊的臺詞。
- 內容提要
- 致謝
- 本書宗旨
- 對本書的贊譽
- 前言
- 第一章 天才程序員的傳說
- 幫我把代碼藏起來
- 天才的傳說
- 隱瞞是有害的
- 團隊才是王道
- 三支柱
- HRT實戰
- 下一步
- 第二章 培養出色的團隊文化
- 什么是文化
- 為什么要關心它
- 文化和人
- 優秀團隊文化中的溝通模式
- 高層面同步
- 每日進行的討論
- 使用bug跟蹤系統
- 溝通也是工程的一部分
- 說到底真正重要的還是代碼本身
- 第三章 大海航行靠船長
- 自然界沒有真空地帶
- @Deprecated Manager
- 主管才是新的經理
- 唯一要擔心的就是……好吧,所有的事情
- 仆人式領導
- 反模式
- 領袖的處事之道
- 人是植物
- 內部激勵和外部激勵
- 結語
- 第四章 對付害群之馬
- 什么是“害群”
- 保護團隊
- 發現威脅
- 第五章 操縱組織的藝術
- 優點、缺點和策略
- 理想的情況:團隊在公司里應該是怎么運作的
- 現實的情況:當環境成為成功路上的絆腳石
- 操縱你的組織
- B計劃:走為上
- 不要放棄
- 第六章 用戶也是人
- 管理大眾的印象
- 管理和用戶之間的關系
- 結語
- 附錄A 延伸閱讀
- 版權