微軟推薦的.net命名規範(1)

許多命名約定都與標識符的大小寫有關。值得注意的是,公共語言運行庫 (CLR) 支持區分大小寫和不區分大小寫的語言。本主題中描述的大小寫約定可幫助開發人員理解和使用庫。

大小寫樣式

下列術語描述了標識符的不同大小寫形式。

Pascal 大小寫

將標識符的首字母和後面連接的每個單詞的首字母都大寫。可以對三字符或更多字符的標識符使用 Pascal 大小寫。例如:

BackColor

大小寫混合

標識符的首字母小寫,而每個後面連接的單詞的首字母都大寫。例如:

backColor

大寫

標識符中的所有字母都大寫。例如:

IO

標識符的大小寫規則

如果標識符由多個單詞組成,請不要在各單詞之間使用分隔符,如下劃線(“_”)或連字符(“-”)等。而應使用大小寫來指示每個單詞的開頭。

下列準則是用於標識符的通用規則。

對於由多個單詞組成的所有公共成員、類型及命名空間名稱,要使用 Pascal 大小寫。

注意,這條規則不適用於實例字段。由於成員設計準則中詳細說明的原因,不應使用公共實例字段。

對參數名稱使用大小寫混合。

下表彙總了標識符的大小寫規則,並提供了不同類型標識符的示例。

 

標識符 大小寫方式 示例

Pascal

AppDomain

枚舉類型

Pascal

ErrorLevel

枚舉值

Pascal

FatalError

事件

Pascal

ValueChanged

異常類

Pascal

WebException

只讀的靜態字段

Pascal

RedValue

接口

Pascal

IDisposable

方法

Pascal

ToString

命名空間

Pascal

System.Drawing

參數

Camel

typeName

屬性

Pascal

BackColor

首字母縮寫詞的大小寫規則

首字母縮寫詞是由術語或短語中各單詞的首字母構成的單詞。例如,HTML 是 Hypertext Markup Language 的首字母縮寫。只有在公衆廣爲認知和理解的情況下,才應在標識符中使用首字母縮寫詞。首字母縮寫詞不同於縮寫詞,因爲縮寫詞是一個單詞的縮寫。例如,ID 是 identifier 的縮寫。通常情況下,庫名不應使用縮寫詞。

注意

可在標識符中使用的兩個縮寫詞是 ID 和 OK。在採用 Pascal 大小寫格式的標識符中,這兩個縮寫詞的大小寫形式應分別爲 Id 和 Ok。如果在採用大小寫混合格式的標識符中將這兩個縮寫詞用作首個單詞,則它們的大小寫形式應分別爲 id 和 ok。

首字母縮寫詞的大小寫取決於首字母縮寫詞的長度。所有首字母縮寫詞應至少包含兩個字符。爲了便於這些準則的實施,如果某一首字母縮寫詞恰好包含兩個字符,則將其視爲短型首字母縮寫詞。包含三個或三個以上字符的首字母縮寫詞爲長型首字母縮寫詞。

下列準則爲短型和長型首字母縮寫詞指定了正確的大小寫規則。標識符大小寫規則優先於首字母縮寫詞大小寫規則。

兩字符首字母縮寫詞的兩個字符都要大寫,但當首字母縮寫詞作爲大小寫混合格式的標識符的首個單詞時例外。

例如,名爲 DBRate 的屬性是一個採用 Pascal 大小寫格式的標識符,它使用短型首字母縮寫詞 (DB) 作爲首個單詞。又如,名爲 ioChannel 的參數是一個採用大小寫混合格式的標識符,它使用短型首字母縮寫詞 (IO) 作爲首個單詞。

包含三個或三個以上字符的首字母縮寫詞只有第一個字符大寫,但當首字母縮寫詞作爲大小寫混合格式的標識符的首個單詞時例外。

例如,名爲 XmlWriter 的類是一個採用 Pascal 大小寫格式的標識符,它使用長型首字母縮寫詞作爲首個單詞。又如,名爲 htmlReader 的參數是一個採用大小寫混合格式的標識符,它使用長型首字母縮寫詞作爲首個單詞。

如果任何首字母縮寫詞位於採用大小寫混合格式的標識符開頭,則無論該首字母縮寫詞的長度如何,都不大寫其中的任何字符。

例如,名爲 xmlStream 的參數是一個採用大小寫混合格式的標識符,它使用長型首字母縮寫詞 (xml) 作爲首個單詞。又如,名爲 dbServerName 的參數是一個採用大小寫混合格式的標識符,它使用短型首字母縮寫詞 (db) 作爲首個單詞。

複合詞和常用術語的大小寫規則

不要將所謂的緊湊格式複合詞中的每個單詞都大寫。這種複合詞是指寫作一個單詞的複合詞,如“endpoint”。

例如,hashtable 是一個緊湊格式的複合詞,應將其視爲一個單詞並相應地確定大小寫。如果採用 Pascal 大小寫格式,則該複合詞爲 Hashtable;如果採用大小寫混合格式,則該複合詞爲 hashtable。若要確定某個單詞是否是緊湊格式的複合詞,請查閱最新的詞典。

通用命名約定

 

通用命名約定討論的是如何爲庫元素選擇最適當的名稱。這些準則適用於所有標識符。後面各節討論特定元素(如命名空間或屬性)的命名。

選擇名稱

請選擇易讀的標識符名稱。例如,英文屬性名稱 HorizontalAlignment 比 AlignmentHorizontal 更具可讀性。

 

可讀性比簡潔性更重要。屬性名稱 CanScrollHorizontally 比 ScrollableX(指 X 軸,但意義不明確)更好。

 

不要使用下劃線、連字符或任何其他非字母數字字符。

 

不要使用匈牙利表示法。

匈牙利表示法是在標識符中使用一個前綴對參數的某些元數據進行編碼,如標識符的數據類型。

程序集和 DLL 的名稱

 

大多數情況下,程序集包含全部或部分可重用庫,且它包含在單個動態鏈接庫 (DLL) 中。一個程序集可拆分到多個 DLL 中,但這非常少見,在此準則中也沒有說明。

程序集和 DLL 是庫的物理組織,而命名空間是邏輯組織,其構成應與程序集的組織無關。命名空間可以且經常跨越多個程序集。

一定要爲程序集 DLL 選擇指示大的功能塊(如 System.Data)的名稱。程序集和 DLL 的名稱不必對應於命名空間名稱,但是在命名程序集時遵循命名空間名稱這種做法是合理的。

 

考慮按下面的模式命名 DLL:

<Company>.<Component>.dll

其中 <Component> 包含一個或多個以圓點分隔的子句。

例如,Contoso.WebControls.dll。

命名空間的名稱

 

爲命名空間選擇的名稱應指示命名空間中的類型所提供的功能。例如,System.Net.Sockets 命名空間包含的類型允許開發人員使用套接字通過網絡進行通信。

命名空間名稱的一般格式如下:

<Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]

例如,Microsoft.WindowsMobile.DirectX。

使用公司名稱作爲命名空間的前綴以防止不同公司開發的命名空間具有相同的名稱和前綴。

 

在命名空間名稱的第二級使用穩定的、與版本無關的產品名稱。

 

不要根據組織層次結構確定命名空間層次結構中的名稱,因爲公司的部門名稱經過一段時間後可能會改變。

命名空間名稱是長期使用的、不會更改的標識符。組織的不斷髮展和變化不應使命名空間名稱過時。

使用 Pascal 大小寫格式,並用句點分隔命名空間各部分(如 Microsoft.Office.PowerPoint)。如果您的品牌採用了非傳統的大小寫,應遵循您的品牌所定義的大小寫,即使它與常用的命名空間大小寫相背離也如是。

 

適當的時候可考慮使用複數命名空間名稱。例如,使用 System.Collections 而不使用 System.Collection。但是,品牌名稱和首字母縮寫詞屬於此規則的例外情況。例如,使用 System.IO,而不要使用 System.IOs。

 

命名空間和其中的類型不要使用相同的名稱。例如,不要在將“Debug”用作命名空間名稱的同時,又在該命名空間中提供一個名爲“Debug”的類。有些編譯器要求對這種類型進行完全限定。

 

命名空間和類型的名稱衝突

如果選擇的命名空間或類型的名稱與現有名稱衝突,則庫的用戶將不得不對受影響的項的引用進行限定。在大多數開發情況中,都不應出現這種問題。

本節提供的某些準則適用於下面的命名空間類別:

  • 應用程序模型命名空間

  • 基礎結構命名空間

  • 核心命名空間

  • 技術命名空間組

應用程序模型中的命名空間提供特定於應用程序中的某個類的功能集。例如,System.Windows.Forms 命名空間中的類型提供編寫 Windows 窗體客戶端應用程序所需的功能。System.Web 命名空間中的類型支持編寫基於 Web 的服務器應用程序。通常,在同一應用程序中不會使用不同應用程序模型中的命名空間,因此,這降低了名稱衝突影響使用您的庫的開發人員的可能性。

基礎結構應用程序提供專門的支持,很少在程序代碼中進行引用。例如,程序開發工具所使用的 *.Designer 命名空間中的類型。*.Permissions 命名空間是基礎結構命名空間的另一個示例。與基礎結構命名空間中的類型的名稱衝突不可能影響使用您的庫的開發人員。

核心命名空間是 System.* 命名空間(不包括應用程序命名空間和基礎結構命名空間)。System 和 System.Text 都是核心命名空間的示例。應儘可能避免與核心命名空間中的類型發生名稱衝突。

屬於特定技術的命名空間將具有相同的第一和第二級標識符 (Company.technology.*)。應避免在技術命名空間中出現名稱衝突。

命名空間一般準則

不要引入寬泛的類型名稱,如 Element、Node、Log 和 Message。在通常情況下,這樣極可能導致類型名稱衝突。應對寬泛的類型名稱進行限定(例如 FormElement、XmlNode EventLog、SoapMessage)。

 

應用程序命名空間準則

不要在單個應用程序模型內爲命名空間中的多個類型指定相同的名稱。

例如,如果要編寫 Windows 窗體應用程序開發人員要使用的特殊控件庫,則不應引入名爲 Checkbox 的類型,因爲該應用程序模型已存在同名類型 (CheckBox)。

核心命名空間準則

不要指定會與核心命名空間中的任何類型發生衝突的類型名稱。

例如,不要使用 Directory 作爲類型名稱,因爲這會與 Directory 類型衝突。

技術命名空間準則

不要分配會與單個技術命名空間內的其他類型發生衝突的類型名稱。

 

不要引入會導致技術命名空間的類型與應用程序模型命名空間中的類型發生衝突的類型名稱(除非該技術不用於該應用程序模型)。

 

發佈了9 篇原創文章 · 獲贊 6 · 訪問量 1372
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章