作為軟體開發者,我們可以開發低等級的軟體,但不能開發低質量的軟體。所以,如何實施質量保證,是我們關注的主要問題之一,而編碼規範則是實施質量保證的第一步。
編碼規範已經成為一個老生常談的問題,幾乎每個專案,每家公司都會定義自己的編碼規範。但在真正實施時,卻在有意或無意地違背編碼規範。程式設計師,不喜歡改變自己的程式設計習慣。加之,管理者對質量控制不足,導致編碼規範往往形同虛設。有些人會認為:遵守編碼規範不能給專案帶來利益,也不能讓客戶看到我們為此付出的努力,其完全是團隊自發的行為,沒有必要做硬性的要求。還有些人有更好的理由:編碼規範會破壞創造性和程式質量。我認為,編碼規範,在軟體構件以及專案管理中,甚至是個人成長方面,都發揮著重要的作用,好的編碼規範是提高我們程式碼質量的最有效的工具之一。
一、編碼規範的作用
- 提高可讀性 “任何一個傻瓜都能寫出計算機可以理解的程式碼,唯有寫出人類容易理解的程式碼,才是優先的程式設計師。”編碼規範,幫助我們寫出人類容易理解的程式碼,它為我們提供了最基本的模板,良好的編碼風格,使程式碼具有一定的描述性,可以通過名字來獲取一些需要IDE才能得到的提示,如可訪問性、繼承基類等。
- 統一全域性,促進團隊協作 開發軟體是一個團隊活動,而不是個人的英雄主義。編碼規範,要求團隊成員遵守這一統一的全域性決策,這樣成員之間可以輕鬆地閱讀對方的程式碼,所有成員正以一種清晰而一致的風格進行編碼。而且,開發人員也可以集中精力關注他們真正應該關注的問題——自身程式碼的業務邏輯,與需求的契合度等區域性問題。
- 有助於知識傳遞,加快工作交接 風格的相似性,能讓開發人員更迅速,更容易理解一些陌生的程式碼,更快速地理解別人的程式碼。因為,他和你的程式碼風格是一樣的,你沒有必要對他的一些個性化風格進行揣測。這樣的好處是開發人員可以很快的接手專案組其他成員的工作,快速完成工作交接。
- 減少名字增生,降低維護成本 在沒有規範的情況下,和容易為同一型別的例項起不同的名字。對於以後維護這些程式碼程式設計師來說會產生疑惑。
- 強調變數之間的關係,降低缺陷引人的機會 命名可以表示一定的邏輯關係,是開發人員在使用時保持警惕,從而一定程度上減少缺陷被引人的機會。
- 提高程式設計師的個人能力 不可否認,每個程式設計師都應該養成良好的編碼習慣,而編碼規範無疑是教材之一。從一個程式設計師的程式碼本身能看出很多東西。所以,即便是為了自身發展,作為程式設計師也沒有理由抵制這種規則的存在。你可能沒有認識到,我們正默默地得益於編碼規範。
二、編碼規範不是“物神”
在高質量的軟體中,你可以看到“架構的概念完整性”與“底層實現”之間的關係。“實現”與“架構”必須是清晰一致的,這種內在的、固有的一致性,需要編碼規範來維繫。如果沒有這種統一的約定,那麼我們做出的東西可能會充斥著各種不同的風格,顯得混亂且難以理解。團隊成員之間可能很不理解彼此之間的想法,甚至是相互抨擊。各種編碼風格上的差異會不斷擴大,而程式碼質量則不斷下降。而且,團隊成員會花費時間在理解不同程式設計風格之間的差異,而沒有專注於真正應該解決的問題。這樣的時間消耗是難以接受的。所以,在每一個高質量程式碼的背後,一定存在著一份優秀的編碼規範。
然而,也必須認識到編碼規範不是“物神”。編碼規範僅僅是一個全域性性質的規範,它只不過是一種程式設計約定,不能解決更深層次的問題。就像一篇格式漂亮但內容糟糕的論文不能被發表一樣,你不能僅靠一個規範來擺脫軟體作坊。而且,在編碼規範中不宜包含那些冗長的開發技巧。我認為,對於程式碼是最佳實踐應該是程式碼審查所要解決的,應該避免將編碼規範寫成一部關於重構的教科書。
三、編寫編碼規範的一些建議
以下是我對定義編碼規範的一些建議:
- 求同存異 不要妄圖改變組織的編碼習慣,除非有絕對合理的理由,否則還是以民主為主,畢竟你沒有權利要求所有人都沿用你的編碼習慣。
- 定義編碼規範越早越好 也早使用編碼規範,也早享受其帶來的好處。
- 將規範分為強制部分和推薦部分 求同存異的具體實現。將最基本的規範列放在強制部分,所有成員必須遵守;將好的但不重要的習慣列在推薦部分,開發人員可以根據自己習慣選擇是否使用。
- 編碼規範不要太長 太長的文件沒人看,所有人都一樣,除了禮品單和工資單沒人願意看長的東西,所以編碼規範必須精煉,最好是隻有2~3頁,讓開發人員可以列印出來隨時檢視。
- 必須是約定俗成的 規範必須是行業中約定俗成的,不要有什麼個性化發揮。
四、編碼規範參考
我本人不太推薦制定過細的編碼規範。制定編碼規範是為了增強程式碼的可讀性,畢竟程式碼的結構才是主要關注問題,所以我的編碼規範還是比較簡短的。裡面只是對可能會破壞編碼風格的行為進行約束,而沒有細化到“空行”甚至“空格”的級別。
編碼規範
一 名稱空間
<公司名稱>.(<產品名稱>|<相關技術>)[.<用途>] [.<子名稱空間>]
二 程式碼風格
- 花括號“{}”不允許省略,即使只有一段程式碼。
- 不允許省略訪問修飾符。
- 型別預設是密封的。
- 不允許公開欄位。
- 使用括號“()”來強調運算子優先順序。
三 命名規範
(一) 類、結構和介面的命名
- 使用名詞或名詞短語。
- 使用Pascal方式。
- 在介面名稱前加上字首“I”。
- 考慮在派生類末尾使用基類的名字。
- 如果該類僅僅為了實現某個介面,那麼請保持其與介面命名的統一。
- 如果從.NET 框架中存在的型別派生的型別,應該遵循以下規範:
基類 | 派生類 |
System.Attribute | 要給自定義的特性新增“Attribute”字尾 |
System.Delegate | 要給用於事件處理的委託新增“EventHandler”字尾
要給用於事件處理之外的那些委託新增“Callback”字尾 不要給委託新增“Delegate”字尾 |
System.EventArgs | 要新增“EventArgs”字尾 |
System.Exception | 要新增“Exception”字尾 |
IDictionary,IDictionary<T,V> | 要新增“Dictionary”字尾 |
IEnumerable,ICollection,IList,
IEnumerable,ICollection,IList |
新增“Collection”字尾 |
System.IO.Stream | 新增“Stream”字尾 |
CodeAccessPermission,IPermission | 新增“Permission”字尾 |
(二) 成員的命名
成員 | 大小寫 | 規範 |
方法 | Pascal(公開)、Camel(私有) | 用動詞或動詞短語命名 |
屬性 | Pascal | 用名詞、名詞短語或形容詞來命名
集合屬性應該使用複數形式,而不是新增字尾 用“Is”、“Can”、“Has”等表示布林屬性 可以用屬性的型別名來命名屬性 |
事件 | Pascal | 使用動詞或動詞短語來命名事件
用現在時和過去時來區分前置和後置事件 |
欄位 | Camel(私有) | 要用名詞、名詞短語或形容詞來命名
不要加任何字首 |
(三) 引數的命名
- Camel風格。
- 要使用left和right來命名過載的二元操作符的引數——如果引數沒有具體的含義。
- 要使用value來命名過載的一元操作符的引數——如果引數沒有具體的含義。
- 不要在引數中使用數字編號。
- 儘量使用描述性的名字命名泛型型別引數,並在前面使用“T”字首。
(四) 常量、變數的命名
- 常量——所有單詞大寫並用“_”分隔。
- 區域性變數——Camel風格。
(五) 列舉的命名
- Pascal風格。
- 使用名詞的複數形式來命名標記列舉。
- 不要新增“Enum”或“Flag”字尾。
- 不要給列舉型別值的名字加字首。
(六) 資源的命名
- Pascal風格。
- 僅使用字母、數字和下劃線。
- 在命名異常訊息的資源時,資源識別符號應該是異常型別名加上簡短的異常識別符號。
(七) 資料庫命名
- 表——“模組名_表名”。
- 欄位——bool型別用“Is”、“Can”、“Has”等表示;日期型別命名必須包含“Date”;時間型別必須包含“Time”。
- 儲存過程——使用“proc_”字首。
- 檢視——使用“view_”字首。
- 觸發器——使用“trig_”字首。
(八) XML命名
節點名稱使用Pascal風格,屬性名稱使用Camel風格。
四 註釋
- 對介面和複雜程式碼塊必須進行註釋。
- 修改程式碼時保持註釋同步。
- 未完成的功能使用TODO標記。
- 修改他人程式碼時要先註釋對方程式碼,並寫明修改原因,不允許隨便刪除他人程式碼。
- 釋出前移除無用註釋。
五 異常處理
- 原則上只允許顯示丟擲InvalidOperationException、ArgumentException、ArgumentNullException和ArgumentOutOfRangeException四種異常型別。
- 在自定義異常時,必須使用VS提供的程式碼模板來建立自定義異常。