.NET設計規範————命名規範

NET設計規範：約定、慣用法與模式———命名規範

前言：

         最近在看《.NET設計規範：約定、慣用法與模式》一書，主要仍是講.NET的設計規範，之前對這一塊也不是特別在乎，最近想要把這些系統的學習一下，如下基本上算是讀書筆記吧。

第三章命名規範

3.1 大小寫約定

使用合適的大小寫可使類型、成員以及參數的標識符更容易閱讀

3.1.1 標識符大小寫原則

爲了區分一個標識符中的多個單詞，把標識符中的每一個單詞的首字母大寫，有如下兩種合適的方法來大寫標識符中的字母，以下：

l  Pascal Casing

l  Camel Casing

PascalCasing約定被用於除了參數名以外的全部標識符，它把標識符中的每一個單詞的首字母大寫。以下所示：

PropertyDescriptor

Html

兩個字母長的首字母縮寫詞是一個特例，在這種狀況下兩個字母都要大寫，以下所示：

IOStream

Camel Casing約定僅用於參數的名字，它把標識符中除了第一個單詞以外的全部單詞的首字母都大寫。以下所示：

propertyDescriptor

html

ioStream（標識符以兩個字母長的的首字母縮寫詞開始，兩個字母都要小寫）

標識符基本大小寫規範：

要把Pascal Casing用於多個單詞構成的名字空間、類型以及成員的名字。

要把Camel Casing用於參數的名字。

不一樣類型的標識符的大小寫規則以下：

3.1.2 首字母縮寫詞的大小寫

避免在標識符的名字中使用首字母縮寫詞是很重要的，除非他們很經常使用，可以被使用框架的人馬上理解，如：HTML、XML等。

從定義上講首字母縮寫詞必須至少有兩個字母。由三個或以上的字母組成的首字母縮寫詞遵循與其餘單詞同樣的規範：只有第一個字母大寫，除非是camelCasing風格的參數名中的第一個單詞，在這種狀況下兩個字母都小寫。以下所示：

Public void StartIO（Stream ioStream，boolcloseIOStream）

Public void PorcessHtmlTag（string htmlTag）

要把兩個字母的首字母縮寫詞所有大寫，除非它是camelCasing風格的參數名的第一個單詞

System.IO

Public void StartIO(StreamioStream)

要把由三個或三個以上字母組成的首字母縮寫詞的第一個字母大寫。除非它是camelCasing風格的參數名的第一個單詞

System.Xml

Public voidProcessHtmlTag(string htmlTag)

不要把camelCasing 風格的標識符頭部的任何首字母縮寫詞的任何字母大寫，不管首字母縮寫詞的長度是多少

3.1.3 複合詞和經常使用術語的大小寫

在涉及大小寫時，大多數複合詞術語要做爲單個單詞處理。

不要把所謂閉合形式的複合詞中每一個單詞的首字母大寫。

例如：endpoint，爲了統一大小寫規範，咱們把閉合形式的複合詞做爲一個單詞處理。

經常使用的複合詞和經常使用術語的大小寫及拼寫，以下圖所示：

 

上邊的示例中有兩個經常使用的的其餘術語，Ok和Id，它們自己是一個類別，由於它們是俚語性質的經常使用縮寫

3.1.4 是否區分大小寫

不要覺得全部的編程語言都是區分大小寫的，實際狀況並不是如此，不該該僅僅經過大小寫來區分名字。

3.2 通用命名約定

本章描述一些通用的命名約定，涉及到單詞的選擇、單詞縮寫、首字母縮寫詞的使用規範以及如何避免使用編程語言特有的名字。

3.2.1 單詞的選擇

對於框架中標識符的名字最重要的一點是一目瞭然。名字意思清楚比長度短更重要，應該與場景、系統的邏輯組成或物理組成以及爲人熟知的概念相對應，不該該與技術活架構相對應。

主要有如下幾點：

要爲標識符選擇易於閱讀的名字。

要更看重可讀性，而非簡短性。

不要使用下劃線、連字符以及其餘任何既非字母也非數字的字符。

不要使用匈牙利命名法。

避免使用與普遍使用的編程語言的關鍵字有衝突的標識符。

3.2.2 使用單詞縮寫和首字母縮寫詞

不要使用縮寫詞和縮約詞做爲標識符名字的一部分。

不要使用未被普遍接受的首字母縮寫詞（即便是被普遍接受的首字母縮寫詞，也只應該在必須的時候才使用）

3.2.3 避免使用語言特有的名字

爲了確保框架可以充分利用跨語言協做，避免在標識符中使用語言特有的類型名是重要的。

要給類型名使用語義上有意義的名字，而不要使用語言特有的關鍵字。

要使用CLR的通用類型名，而不要使用語言特有的別名----若是除了類型以外，標識符沒有其餘的語義。

要使用常見的名字，好比value或item，而不要重複類型的名字----若是除了類型以外，標識符沒有其餘的語義，並且參數的類型不重要。

3.2.4 爲已有API的新版本命名

本節主要描述了當用新類型和新成員接替或取代已有的類型或成員時，如何爲它們選擇名字。

要在建立已有API的新版本時使用與舊API類似的名字，這有利於突出API之間的關係。

   例如：class AppDommain{}

        Class AppDommainSetup{}

要優先使用後綴而不是前綴來表示已有API的新版本。

考慮使用全新但有意義的標識符，而不是簡單的給已有標識符添加後綴或前綴。

要使用數字後綴來表示已有API的新版本—若是已有API的名字時惟一有意義的名字，不宜添加後綴。

例如：publicclass X509Certificate{}

      Public class X509Certificate2{}

不要在標識符中使用「Ex」後綴來區分相同API的不一樣版本。

例如：publicclass Car{}

      Public class CarEx{}  //錯誤的示例

3.3 程序集和DLL的命名

程序集是一個部署單元，同時還表明託管代碼程序的身份。通常來講一個程序集僅與一個DLL相對應。本節主要講DLL命名約定，程序集的命名約定與此相似。

要記住，名字空間與DLL和程序集是不一樣的概念。名字空間對開發人員來講是一組邏輯實體，而DLL和程序集則是在打包和部署時的一個單元。

要爲程序集和DLL選擇提示性的名字（例如：System.Data）這樣很容易就知道它的大體功能。程序集和DLL的名字不必定要和名字空間相對應，但在程序集命名時遵循名字空間的名字也是合情合理的。

考慮按照以下的模式給DLL命名：

<Company>.<Component>.dll

其中<Component>包含一個或多個以點號分隔的字句，如：

Microsoft.VisualBasic.dll

Microsoft.VisualBasic.Vsa.dll

3.4 名字空間的命名

命名空間的目標是清晰，方便框架的使用者。通常的名字空間命名規則以下：

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

示例以下：

Microsoft.VisualStudio

Microsoft.VisualStudio.Design

Litware.Security

l  要用公司名稱做爲名字空間的前綴，這樣就能夠避免與另外一家公司使用相同的名字。

l  要用穩定的、與版本無關的產品名稱做爲名字空間的第二層。

l  不要根據公司的組織架構來決定名字空間的層次結構，由於公司內部組織的名稱通常來講不會持續太長的時間。

l  要使用PascalCasing大小寫風格，並用點號來分隔名字空間中的各部分（例如：Microsoft.office.PowerPoint）.若是商標使用了非傳統的大小寫風格，那麼即便該風格與常規大小寫風格相背，也仍是應該遵循商標的大小寫風格。

l  考慮在適當的時候在名字空間中使用負數形式。

    例如：要用System.Collections而不要用System.Collection。商標和首字母縮寫詞除外。

l  不要用相同的名字來命名名字空間與位於該名字空間中的類型。

    例如：不要將名字空間命名爲Debug，而後又在該名字空間中提供一個名爲Debug的類。

名字空間與類型名的衝突

名字空間用來把類型組織成一個邏輯的、易於瀏覽的層次結構。對解決在導入多個名字空間時可能引發的類型名的二義性，它們是不可或缺的。

不要引入太通常化的類型名（例如：Element，Node，Log，Message）

    這樣的名字很容易引發類型衝突，名字空間能夠分爲下面的類別：

l  應用程序模型名字空間（application model namespace）

l  基礎設施名字空間（infrastructure namespace）

l  核心名字空間（core namespace）

l  技術名字空間組（technology namespace group）

1.      應用程序模型名字空間

不要給位於同一個應用程序模型的名字空間中的類型起相同的名字。

2.      基礎設施名字空間

這個類別包含了一些再開發經常使用的應用程序時不多會導入的名字空間。

3.      核心名字空間

核心名字空間包含了全部的System名字空間，但應用程序模型名字空間和基礎設置名字空間除外。（核心名字空間包括System、System.IO、System.Xml、System.Net等）

不要給類型會與核心名字空間中的任何類型產生衝突的名字。（例如：不要用Stream來做爲類型名，它會和System.IO.Stream產生衝突）

4.      技術名字空間組

這個類別包括全部那些以相同的兩個前綴（<Company>.<Technology>*）開始的名字空間（例如：Microsoft.Build.Utilities和Microsoft.Build.Tasks屬於同一個技術類型，可是彼此之間不衝突）

不要給類型會與位於同一技術組中的其餘類型產生衝突的名字。

不要在技術名字空間和應用程序模型名字空間的類型之間引入類型名衝突（例如：不該給Microsoft.VisualBasic名字空間增長一個Binding類型，由於System.Windows.Forms名字空間已包含該類型名）

3.5 類、結構和接口的命名

通常來說，類型名應該是名詞詞組，由於他們表明了系統中的實體，若是沒法爲類型找到一個名詞詞組，那麼可能應該從新考慮該類型的整體設計。

最易識別的名字應該用於最經常使用的類型，最經常使用的類型名應該反映出使用場景，而不是繼承層次。大多數用戶只是用繼承層次的葉節點，而不關心類層次結構。

下面的命名規範適用於通常的類型命名。

要用名詞或者名詞詞組來給類型命名，在極少數狀況下也能夠用形容詞詞組來給類型命名。(命名時用PascalCasing大小寫風格，這使類型名和方法區分開，後者用動詞詞組來命名。)

不要給類名加前綴。（惟一的前綴是用於接口「I」）

考慮讓派生類的名字以基類的名字結尾。(例如：publicclass FileStream：Stream{…})

要讓接口的名字以字母I開頭，這樣能夠顯示出該類型是一個接口。（例如：IComponent）

要確保一對類/接口的名字只差一個「I」前綴，若是該類是該接口的標準實現。

     例如： public interface IComponent{…}

            Public class Component :IComponent{…}

3.5.1 泛型類型參數的命名

泛型是.NET框架2.0一個主要特徵，它引入了一種稱爲「類型參數（type parameter）」的新標識符。如下的規範描述了與類型參數有關的命名約定。

要用描述性的名字來命名泛型類型參數，除非一個字母就夠了，並且描述性的名字並不能增添什麼價值。

    例如：public interface TSessionChannel<TSession>{…}

          Public class List<T>{…}

考慮用T來命名參數類型——若是類型只有一個類型參數，且類型參數只有一個字母。

    例如：public int IComparer<T>{…}

          Public delegate boolPredicate<T>(T item);

要給描述性的類型參數名加上T前綴。

    例如：public interface ISessionChannel<TSession> whereTSession:ISession

{

    TSession Session{get;}

}

考慮在類型參數名中顯示出施加於該類型參數上的限制。

3.5.2 經常使用類型的命名

若是要從.NET框架所包含的類型派生新類型，或者要實現.NET框架中的類型，要遵循下表的一個命名規則。以下所示：

3.5.3 枚舉類型的命名

通常來講，枚舉類型的命名應該遵循標準的命名規則（PascalCasing 大小寫風格）。可是還有一些針對枚舉類型的具體規範。

要用單數名詞來命名枚舉類型，除非它表示的事位域（bit field）

要用複數名詞來命名錶示位域的枚舉類型，這樣的枚舉類型也稱爲標記枚舉（flag enum）

    例如：[Flags]

          Public enum ConsoleModifiers{

          Alt,

          Control,

          Shift

          }

不要給枚舉類型的名字添加「Enum」後綴。

    例如： public enum ColorEnum{…}//這樣就很差

不要給枚舉類型值的名字添加前綴。

    例如：public enum ImageMode{

              ImageModeBitmap=0，

               ImageModeGrayScale=1，

               ImageModeRgb=2

         }

    下邊的命名會更好：

          Public enum ImageMode{

               Bitmap=0，

               GrayScale=1，

               Rgb=2

          }

3.6 類型成員的命名

類型由方法、屬性、事件、構造函數以及字段等成員組成。

3.6.1 方法的命名

由於方法是用來執行操做的，所以框架的設計規範要求方法名必須是動詞或者動詞詞組。它還用來把方法同屬性和類型名區分開，屬性和類型名是名詞或形容詞詞組。

要用動詞或動詞詞組來命名方法。

3.6.2 屬性的命名

與其餘成員不一樣，屬性應該用名詞詞組或形容詞詞組來命名。命名時要始終使用PascalCasing大小寫風格。

要用名詞、名詞詞組或形容詞來命名屬性。

不要讓屬性名看起來與「Get」方法的名字類似。

要用確定性的短信（CanSeek而不是CantSeek）來命名布爾屬性。若是有幫助，還能夠有選擇性的給布爾值屬性添加「Is」，「Can」，「Has」等前綴。

考慮用屬性的類型名來命名屬性。

    例如：public enum Color{…}

          Public class Control{

              Public Color Color{get{…} set{…}}

          }

3.6.3 事件的命名

事件老是表示一些動做，要麼正在發生，要麼已經發生。所以和方法同樣，要用動詞來命名，此外，還要用動詞的時態來表示事件發生的時間。

要用動詞或動詞短語來命名事件。（例如：Clicked，DroppedDown等）

要用如今時和過去時來賦予事件名以以前和以後的概念。

    例如：在窗口關閉以前的close事件命名爲Closing，關閉以後的事件命名爲Closed

不要用「Before」或「After」前綴或後綴來區分前置和後置事件。

要在命名事件處理函數時加上「EventHandler」後綴。（例如：public delegate void ClickedEventHandler（object sender，ClickedEventArgse）；

要在事件處理函數中用sender 和e做爲兩個參數的名字。

    參數sender表示觸發該事件的對象。

要在命名事件的參數類時加上「EventArgs」後綴。

3.6.4 字段的命名

    字段的命名規範適用於靜態共有字段和靜態受保護字段。

    要在命名字段時使用PascalCasing大小寫風格。

    要用名詞或名詞短語來命名字段。

不要給字段名添加前綴。（例如：不要用「g_」或」s_」來區分靜態和非靜態字段）

3.7 參數的命名

要在命名參數時使用camelCasing大小寫風格。

要使用具備描述性的參數名。

    參數名應該具備足夠的描述性，在大多數狀況下，用戶根據參數名字和類型就可以肯定它的意思。

考慮根據參數的意思而不是參數的類型來命名參數。

3.8 資源的命名

本地化的資源就比如是屬性，能夠經過特定的對象來引用。所以資源的命名規範與屬性的命名規範類似。

要在命名資源關鍵字時使用PascalCasing大小寫風格。

要使標識符的名字具備描述性而不是使名字變短。

不要使用各類CLR編程語言特有的關鍵字。

要在命名資源時僅使用字母、數字和下劃線。

要用點號來給標識符清楚的劃分層次。

    例如：設計菜單系統資源，命名方式以下：

          Menus.FileMenu.Close.Text

        Menus.FileMenu.Close.Color

要在爲異常的消息資源命名時遵循下面的命名約定：

    資源標識符應該是異常的類型名加上一個簡短的異常標識符，之間以點號分隔：

    ArgumentException.IllegalCharacters

    ArgumentException.InvalidName