《.NET 設計規範》第 8 章：使用規範

標籤：時序   支援   一個   狀態   hashtable   調用   map   作用   eth   

第 8 章：使用規範8.1 數組

　　要在公用 API 中優先使用集合，避免使用數組。

　　不要使用唯讀數組欄位。雖然欄位本身是唯讀，使用者不能修改它們，但使用者可以修改數組中的元素。

　　考慮使用不規則數組，而不要使用多維陣列。

　　

8.2 修飾屬性

　　要在命名自訂修飾屬性類時添加“Attribute”尾碼。

　　要在定義自己的修飾屬性時使用 AttributeUsageAttribute。

　　要將必填參數定義為唯讀屬性。

　　要提供建構函式參數來對必填參數進行初始化。每個參數的名字應該與對應屬性的名字相同（但大小寫會不同）。

　　避免提供建構函式參數來對可選屬性（選擇性參數）進行初始化。

　　避免對自訂修飾屬性的建構函式進行重載。

　　要儘可能將自訂修飾屬性類密封起來。這樣會使對修飾屬性的尋找更快。

　　

8.3 集合

　　不要在公用 API 中使用弱類型集合。

　　不要在公用 API 中使用 ArrayList 或 List<T>。

　　不要在公用 API 這種使用 Hashtable 或 Dictionary<TKey, TValue>。

　　不要使用 IEnumerator<T>、IEnumerator 或實現了這兩個介面之一的任何其他類型，除非是作為 GetEnumerator 方法的傳回型別。

　　不要在同一類型中同時實現 IEnumerator<T> 和 IEnumerable<T>。對非泛型介面 IEnumerator 和 Enumerable 來說也同樣如此。

　　要用最泛的類型來作為參數類型。大多數以集合為參數的成員都使用 IEnumerable<T> 介面。

　　避免使用 ICollection<T> 或 ICollection 來做參數 - 如果其目的僅僅只是為了訪問該介面的 Count 屬性。

　　不要提供可設定的集合屬性。

　　要用 Collection<T> 或其子類 - 如果屬性或傳回值表示可讀寫的集合。

　　要用 ReadOnlyCollection<T> 或其子類，在少數情況下用 IEnumerable<T>，如果屬性或傳回值表示唯讀集合。

　　考慮使用泛型集合基類的子類，而不要直接使用該集合。

　　考慮用 Collection<T> 或 ReadOnlyCollection<T> 的子類來作為常用方法和常用屬性的傳回值。

　　考慮使用有鍵集合 - 如果集合這種儲存的元素都有獨一無二的索引值（名字、ID 等等）。有鍵集合是一個能同時以整數值和索引值為索引來訪問的集合，在實現時通常會讓它們派生自 KeyedCollection<TKey, TItem>。

　　不要從集合屬性或以集合為傳回值的方法中返回 null。而要返回一個空集合或空數組。

　　不要讓屬性返回快照集合，屬性應該返回實況集合。

　　要用快照集合或實況的 IEnumerable<T>（或它的子類）來表示不穩定的集合（也就是說，無需顯式地修改就可能會發生改變的集合）。

　　不要讓屬性返回快照集合，屬性應該返回實況集合。

　　要用快照集合或實況的 IEnumerable<T> （或它的子類）來表示不穩定的集合（也就是說，無需顯式地修改就可能會發生改變的集合）。

　　要在設計新的集合時實現 IEnumerable<T>。如果合理，還可以考慮實現 ICollection<T> 甚至 IList<T>。

　　考慮實現非泛型集合介面（IList 和 ICollection）- 如果經常需要把集合傳給以這些參數為輸入的 API。

　　避免為類型實現集合介面 - 如果類型的 API 很複雜，而且與集合的概念無關。

　　不要繼承自非泛型的集合基類，比如 CollectionBase。要使用 Collection<T>，ReadOnlyCollection<T>，以及 KeyedCollection<TKey, TItem>。

　　要在為類型命名時添加“Dictionary”尾碼 - 如果類型實現了 IDictionary 或 IDictionary<TKey, TValue> 介面。

　　要在為類型命名時添加“Collection”尾碼 - 如果類型實現了 IEnumerable（或它的任何子類）介面，並且類型表示的是一個元素列表。

　　要在命名自訂的資料結構時，使用合適的資料結構名。

　　避免在為集合抽象命名時添加代表其具體實現的尾碼，比如“LinkedList”或“Hashtable”。

　　考慮用集合元素的類型名作為集合名字的首碼。

　　考慮給唯讀集合的名字添加“ReadOnly”首碼，如果今後有可能會增加與之對應的可寫集合，或與之對應的可寫集合在架構中已經存在。

 

8.4 DateTime 和 DateTimeOffset

　　要使用 DateTimeOffset - 如果想要表示一個精確地時間點。例如，用它來計算現在的時間、事務開始的時間、檔案修改的時間、記錄事件的時間，等等。如果不知道時區，那麼就使用 UTC。與 DateTime 更實用的情境相比，上述情境更加常見，因此在預設情況下應該使用 DateTimeOffset。

　　要在任何不適合使用絕對時間點的情況下使用 DateTime，比如能適用於不同時區的商店開門的時間。

　　要在不知道時區或有時候不知道時區的情況下使用 DateTime。如果資料來自老式系統，那麼可能會發生這種情況。

　　不要在能夠使用 DateTimeOffset 的時候使用 DateTimeKind。

　　要用 DateTime 來表示所有的日期（比如生日），並將時間部分設為 00:00:00.不要用 DateTimeOffset 來表示日期。

 

8.5 ICloneable

　　不要實現 ICloneable。

　　不要在公用 API 中使用 ICloneable。

　　考慮為需要複製機制的類型定義 Clone 方法。一定要在文檔中明確說明該方法執行的是深複製還是淺複製。

　　

8.6 IComparable<T> 與 IEquatable<T>

　　要為實值型別實現 IEquatable<T>。

　　要在實現 IEquatable<T>.Equals 時，同樣遵循為覆蓋 Object.Equals 而制定的規範。

　　要在實現 IEquatable<T> 的同時覆蓋 Object.Equals。

　　考慮在實現 IEquatable<T> 的同時重載 operator == 和 operator !=。

　　要在實現 IComparable<T> 的同時實現 IEquatable<T>。

　　考慮在實現 IComparable<T> 的同時重載比較操作符（<、>、<=、>=）。

　

8.7 IDisposable

 

8.8 Nullable<T>

　　考慮用 Nullable<T> 來表示那些可能不存在的值（比如可選的值）。舉個例子，如果要從資料庫中返回一個強型別的記錄，並且其中有一個屬性對應的是表中一個可有可無的列，那麼就應該使用 Nullable<T>。

　　不要使用 Nullable<T> - 除非在類似的情況下你會因為參考型別可以為 null 而考慮用參考型別來代替它。例如，不應該用 null 來表示選擇性參數。

　　避免用 Nullable<bool> 來表示通用的具有三種狀態的值。Nullable<bool> 應該只用來表示真正可選的布爾值：true、false 以及不可用。如果至少是想表示具有三種狀態的值（例如 yes、no、cancel），那麼可以考慮使用枚舉。

　　避免使用 System.DBNull。要優先使用 Nullable<T>。

 

8.9 Object

　　要在覆蓋 Object.Equals 方法時，遵守它定義的契約。

　　要在覆蓋 Equaals 方法的同時覆蓋 GetHashCode 方法。

　　考慮在覆蓋 Object.Equals 方法的同時實現 IEquatable<T> 介面。

　　不要從 Equals 方法中拋出異常。

　　要覆蓋實值型別的 Equals 方法。

　　要通過實現 IEquatable<T> 來提供一個以該實值型別本身為參數的 Equals 重載方法。

　　考慮覆蓋 Equals 以提供值相等語義 -  如果參考型別表示的是一個值。例如，對那些表示數值或其他數學試題的參考型別來說，可以考慮覆蓋 Equals 方法。

　　不要為可變的參考型別實現值相等語義。

　　要覆蓋 GetHashCode 方法 - 如果覆蓋了 Object.Equals 方法。

　　要確保對任何兩個對象來說，如果 Object.Equals 方法返回 true，那麼它們的 GetHashCode 方法的傳回值也應該相同。

　　要竭盡所能讓類型的 GetHashCode 方法產生隨機分布的散列碼。

　　要確保無論怎麼更改對象，GetHashCode 都會返回完全相同的值。

　　避免從 GetHashCode 方法中拋出異常。

　　要覆蓋 ToString 方法 - 只要能返回既有用，又易於讓人閱讀的字串。

　　要盡量讓 ToString() 方法返回短小的字串。

　　考慮為每一個執行個體返回一個獨一無二的字串。

　　要使用易於閱讀的名字，而不要使用雖然獨一無二，但卻讓人無法理解的 ID。

　　要在返回與地區性有關的資訊時，根據當前線程的地區性來對字串進行格式化。

　　要提供重載方法 ToString(string format) 或實現 IFormattable 介面 - 如果 ToString() 方法返回的字串與地區性有關，或者有多種方法來對字串進行格式化。例如，DateTime 既提供了重載方法，又實現了 IFormattable 介面。

　　不要從 ToString() 方法返回Null 字元串或 null。

　　避免從 ToString() 方法中拋出異常。

　　要確保 ToString() 方法不會產生副作用。

　　要通過 ToString() 的覆蓋方法來報告與安全性有關的資訊，前提是必須先獲得相應的許可。如果無法獲得許可，那麼應該在返回的字串中去除對安全性有關的資訊。

　　考慮讓 ToString 方法輸出的字串能夠為該類型的解析方法正確地解析。

　　

8.10 序列化

　　要在設計心得類型時考慮到序列化。

　　考慮讓類型支援資料合約序列化 - 如果需要在 Web 服務中使用該類型，或需要在 Web 服務中對該類型進行持久化。

　　考慮讓類型只支援 XML 序列化，或同時支援資料合約序列化和 XML 徐麗華 - 如果需要在徐麗華類型時產生的 XML 的格式有更多的控制。

　　考慮讓類型支援運行時序列化 - 如果需要跨越 .NET Remoting 的邊界傳輸類型。

　　不要僅僅為了進行一般的持久化而支援 XML 序列化或運行時序列化。應該優先支援資料合約序列化。

　　考慮將類型中的成員定義為公有的 - 如果類型會被用於不完全可信的環境。

　　要為所有應用了 DataMemberAttribute 的屬性實現 getter 和 setter。為了能夠讓資料合約序列化程式對類型進行序列化，屬性必須有 getter 和 setter。如果類型不會用於不完全可信的環境中，那麼 getter 和 setter 中的一個或兩個可以不是公有的。

　　要用序列化毀掉函數來對反序列的執行個體進行初始化。

　　考慮使用 KnownTypeAttribute 來表示那些在還原序列化複雜的對象圖時應該會用到的具體類型。

　　要在建立或改變可序列化的類型時考慮向後相容性和向前相容性。

　　考慮為了支援新老版本的雙向轉換而實現 IExtensibleDataObject。

　　避免在設計類型時特別考慮 XML 序列化，除非有強烈的理由要對產生的 XML 內容加以控制。XML 序列化技術已經被前面介紹的資料合約序列化技術所取代。

　　考慮實現 IXmlSerializable 介面 - 如果應用 XML 序列化修飾屬性後產生的 XML 內容還不能滿足需要。這個介面有兩個方法，ReadXml 和 WriteXml，可以用他們來完全控制產生的 XML 內容。還可以給類型應用 XmlSchemaProviderAttribute 來對產生的 XML 結構描述加以控制。

　　考慮支援運行時序列化 - 如果類型會被用於 NET Remoting。例如，由於 System.AddIn 命名空間用到了 .NET Remoting，因此在 System.AddIn 的增益集（add-in）之間傳輸的所有類型都必須支援運行時序列化。

　　考慮實現運行時序列化模式 - 如果想要完全控制序列化的整個過程。例如，想在序列化或反序列的時候進行資料轉換。

　　要將序列化建構函式定義為受保護的，並提供兩個參數，參數的類型和命名要和下面的範例代碼完全相同。

　　要顯式地實現 ISerializable 介面的成員。

　　要給 Iserializable.GetObjectData 的實現應用一個連結要求，這樣做是為了保證只有完全可信的代碼和運行時序列化程式才能訪問該成員。

 

8.11 Uri

　　要使用 System.Uri 來表示 URI 和 URL 資料。

　　考慮為最常用的帶 System.Uri 參數的成員提供基於字串的重載成員。

　　不雅不假思索地為所有基於 System.Uri 的成員提供基於字串的重載成員。

　　要調用基於 System.Uri 的重載成員 - 如果有的話。

　　不要在字串中儲存 URI/URL 資料。

　　

8.12 System.Xml 的使用

　　不要用 XmlNode 或XmlDocument 來表示 XML 資料。要盡量使用 IXPathNavigable、XmlReader、XmlWriter 或 XNode 的子類型。XmlNode 和 XmlDocument 的設計目的並不是為了公開暴露給外界的 API。

　　要在接受 XML 或返回 XML 的成員中，以 XmlReader、IXPathNavigable 或 XNode 的子類型為輸入或輸出。

　　不要從 XmlDocument 派生子類 - 如果想要建立的類型表示下層物件模型或資料來源的 XML 視圖。

　　

8.13 相等性操作符

　　

《.NET 設計規範》第 8 章：使用規範