許多命名約定都與標識符的大小寫有關。值得注意的是,公共語言運行庫 (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 選擇指示大的功能塊(如 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 類型沖突。