一組一致的的命名約定對框架的可用性及其重要。 名字要易于理解,同時(shí)必須傳達(dá)每個(gè)元素的功能。
大小寫約定
標(biāo)識(shí)符的大小寫規(guī)則
PascalCasing:如HtmlTag IOStream
camelCasing:如htmlTag ioStream
- 要把PascalCasing用于由多個(gè)單詞構(gòu)成的名字空間、類型、以及成員的名字;
- 要把camelCasing用于參數(shù)的名字。
通用命名約定
單詞的選擇
對框架中標(biāo)識(shí)符的名字來說,很重要的一點(diǎn)是一目了然。
名字的意思清楚比長度短更重要。名字應(yīng)該與場景、系統(tǒng)的邏輯組成或物理組成以及為人熟知的概念相對應(yīng),而不應(yīng)該與技術(shù)或框架相對應(yīng)。
- 要為標(biāo)識(shí)符選擇易于閱讀的名字;
- 要更看重可讀性,而不是更看重簡短性;
- 不要使用下劃線、連字符以及其他任何既非字母也非數(shù)字的字符;
- 不要使用匈牙利命名法;
- 避免使用與廣泛使用的編程語言的關(guān)鍵字有沖突的標(biāo)識(shí)符。
使用單詞縮寫和首字母縮寫詞
一般來說,不要在標(biāo)識(shí)符中使用單詞縮寫或首字母縮寫:寧可名字長一點(diǎn),也不要?jiǎng)e人看不懂。 尤其不要使用未被廣泛接受的單詞縮寫和首字母縮寫詞。
- 不要使用縮寫詞或縮略詞作為標(biāo)識(shí)符名字的一部分
用GetWindow 不用GetWin - 不要使用未被廣泛接受的首字母縮寫詞
多謂廣泛接受:用搜索引擎在網(wǎng)上搜索該首字母縮寫詞,如果返回的前幾個(gè)結(jié)果與期望相符,那么該首字母縮寫詞才有資格被稱為眾所周知。
避免使用語言特有的名字
- 要給類型名使用語義上有意義的名字,而不要使用特有的關(guān)鍵字
GetLength比GetInt要好 - 要使用CLR的通用類型名,而不要使用語言特有的別名
- 要使用常見的名字,比如value或item,而不要重復(fù)類型的名字
為已有API的新版本命名
當(dāng)用新類型和新成員接替或取代已有的類型或成員時(shí),如何選擇名字:
- 使用與舊API相似的名字
- 要優(yōu)先使用后綴而不是前綴來表示已有API的新版本
這樣有助于在瀏覽文檔或使用Intellisense時(shí)發(fā)現(xiàn)新版本:按字母排序 - 可以考慮使用全新但有意義的標(biāo)識(shí)符
- 要使用數(shù)字后綴來表示已有API的新版本
有些名字(或工業(yè)標(biāo)準(zhǔn))不宜添加后綴或改名 - 不要在標(biāo)識(shí)符中使用“Ex”“New”等類似的后綴來區(qū)分相同API的不同版本
- 要在引入64位整數(shù)(long)而非32位整數(shù)進(jìn)行操作的新版本API時(shí)使用“64”后綴,反之亦然。
程序集和DLL的命名
程序集是一個(gè)部署單元,同時(shí)還代表托管代碼程序的身份。雖然程序集可以分布一個(gè)或多個(gè)文件中,但一般來說一個(gè)程序集僅與一個(gè)DLL相對應(yīng)。
名字空間與DLL程序集的區(qū)別:
名字空間:一組邏輯實(shí)體
DLL和程序集:打包和部署時(shí)的一個(gè)單
- 要為程序集和DLL選擇提示性的名字,比如System.Data,這樣很容易就知道它的大致功能。
- DLL命名:<Company>.<Component>.dll
名字空間的命名
<Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]
- 要用公司名稱作為名字空間的前綴,不要用縮寫
- 要用穩(wěn)定的與版本無關(guān)的產(chǎn)品名稱作為名字空間的第二層
- 不要根據(jù)公司的組織架構(gòu)來決定名字空間的層次結(jié)構(gòu),因?yàn)楣緝?nèi)部組織的名稱一般來說不會(huì)持續(xù)太長的時(shí)間
- 要使用PascalCasing大小寫風(fēng)格,并用點(diǎn)號(hào)來分隔名字空間的各部分。
如Microsoft.Office.PowerPoint - 考慮適當(dāng)?shù)臅r(shí)候在名字空間中使用復(fù)數(shù)形式。 首字母縮寫詞例外
System.Collections
System.IO - 不要用相同的名字來命名名字空間與位于該名字空間中的類型
如:不要將名字空間命名為Debug,然后又在該名字空間中提供一個(gè)名為Debug的類。
名字空間和類型沖突
- 不要引入太一般化的類型名,比如Element、Node、Log以及Message。
不同類型的名字空間,有不同的規(guī)范來避免類型名的沖突:
- 應(yīng)用程序模型名字空間(application model namespace)
屬于單個(gè)應(yīng)用程序模型的名字空間經(jīng)常一起使用,但是它們幾乎不合屬于其他應(yīng)用程序模型的名字空間一起使用
System.Windows*
System.UI* - 基礎(chǔ)設(shè)施名字空間(infrastructure namespace)
此類別包含一些在開發(fā)常用應(yīng)用程序時(shí)很少會(huì)導(dǎo)入的名字空間 - 核心名字空間(core namespace)
包含了所有的System名字空間,但應(yīng)用程序模塊名字空間和基礎(chǔ)設(shè)施名字空間除外。 包括System、System.IO、System.Xml以及System.Net等等 - 技術(shù)名字空間組(technology namespace group)
此類別包含所有那些以相同的兩個(gè)前綴(<Company>.<Technology>*)開始的名字空間。
類、結(jié)構(gòu)和接口的命名
一般來說類型名應(yīng)該是名詞詞組。如果無法為類型找到一個(gè)名詞詞組,那么應(yīng)該重新考慮類型的總體設(shè)計(jì)。
另一個(gè)中重要的考慮因素:最易于識(shí)別的名字應(yīng)該用于最常用的類型。
最常用的類型名應(yīng)該反映出使用場景,而不是繼承層次。
- 要用名詞詞組來給類型命名。使用PascalCasing風(fēng)格
- 不要給類名加前綴
只有接口才能(可以)被加前綴“I”,那是因?yàn)?NET框架受到COM及Java的影響 - 考慮讓派生類的名字以其基類結(jié)尾
public class FileStream : Stream {...} - 要確保一對類/接口的名字只差一個(gè)“I”前綴,如果該類是該接口的標(biāo)準(zhǔn)實(shí)現(xiàn)。
public interface IComponent {...}
public class Component : IComponent {...}
泛型類型參數(shù)的命名
- 要用描述性的名字來命名
- 考慮用T來命名參數(shù)類型
- 要給描述性的類型參數(shù)名加上T前綴
- 考慮在類型參數(shù)中顯示出施加于該類型參數(shù)上的限制
枚舉類型的命名
- 要用單數(shù)名詞來命名枚舉類型,除非它表示的是位域(bit field)
- 不要給枚舉類型的名字添加“Enum”后綴,也不要添加“Flag”、“Flags”等后綴
- 不要給枚舉類型值的名字添加前綴
此規(guī)范與C++中通常所使用的恰好相反。在C++中給枚舉的每個(gè)成員加上完成的限定符是很重要的,因?yàn)樗鼈兛赡茉诿杜e名的作用域之外被訪問。但是在托管代碼中,枚舉成員只能通過枚舉名的作用域來訪問。
類型成員的命名
類型:方法、屬性、事件、構(gòu)造函數(shù)、字段
方法的命名
要盡量根據(jù)方法所對應(yīng)的任務(wù)來給它們命名,而不要根據(jù)一些實(shí)現(xiàn)細(xì)節(jié)。
- 要用動(dòng)詞或動(dòng)詞詞組來命名方法
屬性的命名
- 要用名詞、名詞詞組或形容詞來命名屬性
- 不要讓屬性名看起來與“Get”方法的名字相似
- 要用肯定性的短語(CanSeek而不是CantSeek)來命名布爾屬性
- 考慮用屬性的類型名來命名屬性
public enum Color {...}
public class Control
{
public Color Color
{
get {...}
set {...}
}
}
事件的命名
- 要用動(dòng)詞或動(dòng)詞短語來命名事件
事件總是表示一些動(dòng)作,要么正在發(fā)生,要么已經(jīng)發(fā)生 - 要用現(xiàn)在時(shí)和過去時(shí)來賦予事件名之前和之后的概念
窗口關(guān)閉之前發(fā)生的close事件:Closing
窗口關(guān)閉之后發(fā)生的close時(shí)間:Closed - 不要用Before和After前綴或后綴來區(qū)分前置和后置事件
- 要在命名事件處理函數(shù)(用作事件類型的委托)時(shí)加上“EventHandler”后綴
- 要在事件處理函數(shù)中用sender和e作為兩個(gè)參數(shù)的名字
sender:觸發(fā)事件的對象,在整個(gè).NET框架中,sender為object類型 - 要在命名事件的參數(shù)類型時(shí)加上“EventArgs”后綴
字段的命名
- PascalCasing風(fēng)格
- 名詞或名詞短語
- 不要給字段名添加前綴
參數(shù)的命名
- camelCasing風(fēng)格
- 要使用描述性的參數(shù)名
參數(shù)名要具備足夠的描述性,使得在大多數(shù)情況下,用戶根據(jù)參數(shù)的名字和類型就能夠確定它的意思 - 考慮根據(jù)參數(shù)的意思而不是參數(shù)的類型來命名參數(shù)
資源的命名
本地化的資源就好比是屬性,可以通過特定的對象來引用。因此,它的命名規(guī)范與屬性的相似。
- 要在命名屬性關(guān)鍵字(resource key)時(shí)使用PascalCasing大小寫風(fēng)格
- 要使標(biāo)識(shí)符的名字具有描述性而不是使名字變短
- 不要使用各主要CLR編程語言特有的關(guān)鍵字
- 要在命名資源時(shí)使用字母、數(shù)字和下劃線
- 要用點(diǎn)號(hào)來給標(biāo)識(shí)符清楚地劃分層次
- 要在為異常消息資源命名是遵循下面的命名約定:
資源標(biāo)識(shí)符應(yīng)該是異常的類型名加一個(gè)簡短的異常標(biāo)識(shí)符,之間以點(diǎn)號(hào)分隔