C# 編碼約定（C# 編程指南） · MSDN C# 編程指南 & 參考手冊 2015

# C# 編碼約定（C# 編程指南） [C# 語言規范](http://go.microsoft.com/fwlink/?LinkId=199552) 未定義編碼標準。但是，Microsoft 根據本主題中的準則來開發樣本和文檔。編碼約定可實現以下目的： * 它們為代碼創建一致的外觀，以確保讀取器專注于內容而非布局。 * 它們使得讀取器可以通過基于之前的經驗進行的假設更快地理解代碼。 * 它們便于復制、更改和維護代碼。 * 它們展示 C# 最佳做法。 ## 命名約定 * 在不包括 [using 指令](https://msdn.microsoft.com/zh-CN/library/sf0df423.aspx)的短示例中，使用命名空間限定。如果你知道命名空間默認導入項目中，則不必完全限定來自該命名空間的名稱。如果對于單行來說過長，則可以在點 (.) 后中斷限定名稱，如下面的示例所示。 ``` var currentPerformanceCounterCategory = new System.Diagnostics. PerformanceCounterCategory(); ``` * 你不必更改通過使用 Visual Studio 設計器工具創建的對象的名稱以使它們適合其他準則。 ## 布局約定好的布局利用格式設置來強調代碼的結構并使代碼更便于閱讀。Microsoft 示例和樣本符合以下約定： * 使用默認的代碼編輯器設置（智能縮進、4 字符縮進、制表符保存為空格）。有關詳細信息，請參閱[選項、文本編輯器、C#、格式設置](https://msdn.microsoft.com/zh-CN/library/03864tbz.aspx)。 * 每行只寫一條語句。 * 每行只寫一個聲明。 * 如果連續行未自動縮進，請將它們縮進一個制表符位（四個空格）。 * 在方法定義與屬性定義之間添加至少一個空白行。 * 使用括號突出表達式中的子句，如下面的代碼所示。 ``` if ((val1 > val2) && (val1 > val3)) { // Take appropriate action. } ``` ## 注釋約定 * 將注釋放在單獨的行上，而非代碼行的末尾。 * 以大寫字母開始注釋文本。 * 以句點結束注釋文本。 * 在注釋分隔符 (//) 與注釋文本之間插入一個空格，如下面的示例所示。 ``` // The following declaration creates a query. It does not run // the query. ``` * 不要在注釋周圍創建格式化的星號塊。 ## 語言準則以下各節介紹 C# 遵循以準備代碼示例和樣本的做法。 ### String 數據類型 * 使用 **+** 運算符來連接短字符串，如下面的代碼所示。 ``` string displayName = nameList[n].LastName + ", " + nameList[n].FirstName; ``` * 若要在循環中追加字符串，尤其是在使用大量文本時，請使用 [StringBuilder](https://msdn.microsoft.com/zh-CN/library/system.text.stringbuilder.aspx) 對象。 ``` var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala"; var manyPhrases = new StringBuilder(); for (var i = 0; i < 10000; i++) { manyPhrases.Append(phrase); } //Console.WriteLine("tra" + manyPhrases); ``` ### 隱式類型的局部變量 * 當變量類型明顯來自賦值的右側時，或者當精度類型不重要時，請對本地變量進行[隱式類型化](https://msdn.microsoft.com/zh-CN/library/bb384061.aspx)。 ``` // When the type of a variable is clear from the context, use var // in the declaration. var var1 = "This is clearly a string."; var var2 = 27; var var3 = Convert.ToInt32(Console.ReadLine()); ``` * 當類型并非明顯來自賦值的右側時，請勿使用 [var](https://msdn.microsoft.com/zh-CN/library/bb383973.aspx)。 ``` // When the type of a variable is not clear from the context, use an // explicit type. int var4 = ExampleClass.ResultSoFar(); ``` * 請勿依靠變量名稱來指定變量的類型。它可能不正確。 ``` // Naming the following variable inputInt is misleading. // It is a string. var inputInt = Console.ReadLine(); Console.WriteLine(inputInt); ``` * 避免使用 **var** 來代替 [dynamic](https://msdn.microsoft.com/zh-CN/library/dd264741.aspx)。 * 使用隱式類型化來確定 [for](https://msdn.microsoft.com/zh-CN/library/ch45axte.aspx) 和 [foreach](https://msdn.microsoft.com/zh-CN/library/ttw7t8t6.aspx) 循環中循環變量的類型。下面的示例在 **for** 語句中使用隱式類型化。 ``` var syllable = "ha"; var laugh = ""; for (var i = 0; i < 10; i++) { laugh += syllable; Console.WriteLine(laugh); } ``` 下面的示例在 **foreach** 語句中使用隱式類型化。 ``` foreach (var ch in laugh) { if (ch == 'h') Console.Write("H"); else Console.Write(ch); } Console.WriteLine(); ``` ### 無符號數據類型 * 通常，使用 **int** 而非無符號類型。 **int** 的使用在整個 C# 中都很常見，并且當你使用 **int** 時，更易于與其他庫交互。 ### 數組 * 當在聲明行上初始化數組時，請使用簡潔的語法。 ``` // Preferred syntax. Note that you cannot use var here instead of string[]. string[] vowels1 = { "a", "e", "i", "o", "u" }; // If you use explicit instantiation, you can use var. var vowels2 = new string[] { "a", "e", "i", "o", "u" }; // If you specify an array size, you must initialize the elements one at a time. var vowels3 = new string[5]; vowels3[0] = "a"; vowels3[1] = "e"; // And so on. ``` ### 委托 * 使用簡潔的語法來創建委托類型的實例。 ``` // First, in class Program, define the delegate type and a method that // has a matching signature. // Define the type. public delegate void Del(string message); // Define a method that has a matching signature. public static void DelMethod(string str) { Console.WriteLine("DelMethod argument: {0}", str); } ``` ``` // In the Main method, create an instance of Del. // Preferred: Create an instance of Del by using condensed syntax. Del exampleDel2 = DelMethod; // The following declaration uses the full syntax. Del exampleDel1 = new Del(DelMethod); ``` ### 異常處理中的 try-catch 和 using 語句 * 對大多數異常處理使用 [try-catch](https://msdn.microsoft.com/zh-CN/library/0yd65esw.aspx) 語句。 ``` static string GetValueFromArray(string[] array, int index) { try { return array[index]; } catch (System.IndexOutOfRangeException ex) { Console.WriteLine("Index is out of range: {0}", index); throw; } } ``` * 通過使用 C# [using 語句](https://msdn.microsoft.com/zh-CN/library/yh598w02.aspx)簡化你的代碼。如果你具有 [try-finally](https://msdn.microsoft.com/zh-CN/library/zwc8s4fz.aspx) 語句（該語句中 **finally** 塊的唯一代碼是對 [Dispose](https://msdn.microsoft.com/zh-CN/library/system.idisposable.dispose.aspx) 方法的調用），請使用 **using** 語句代替。 ``` // This try-finally statement only calls Dispose in the finally block. Font font1 = new Font("Arial", 10.0f); try { byte charset = font1.GdiCharSet; } finally { if (font1 != null) { ((IDisposable)font1).Dispose(); } } // You can do the same thing with a using statement. using (Font font2 = new Font("Arial", 10.0f)) { byte charset = font2.GdiCharSet; } ``` ### && 和 || 運算符 * 若要通過跳過必要的比較來避免異常和提高性能，請在執行比較時使用 [&&](https://msdn.microsoft.com/zh-CN/library/2a723cdk.aspx) 來代替 [&](https://msdn.microsoft.com/zh-CN/library/sbf85k1c.aspx)，使用 [||](https://msdn.microsoft.com/zh-CN/library/6373h346.aspx) 來代替 [|](https://msdn.microsoft.com/zh-CN/library/kxszd0kx.aspx) ，如下面的示例所示。 ``` Console.Write("Enter a dividend: "); var dividend = Convert.ToInt32(Console.ReadLine()); Console.Write("Enter a divisor: "); var divisor = Convert.ToInt32(Console.ReadLine()); // If the divisor is 0, the second clause in the following condition // causes a run-time error. The && operator short circuits when the // first expression is false. That is, it does not evaluate the // second expression. The & operator evaluates both, and causes // a run-time error when divisor is 0. if ((divisor != 0) && (dividend / divisor > 0)) { Console.WriteLine("Quotient: {0}", dividend / divisor); } else { Console.WriteLine("Attempted division by 0 ends up here."); } ``` ### New 運算符 * 隱式類型化時，請使用對象實例化的簡潔形式，如下面的聲明所示。 ``` var instance1 = new ExampleClass(); ``` 上一行等同于下面的聲明。 ``` ExampleClass instance2 = new ExampleClass(); ``` * 使用對象初始值設定項來簡化對象創建。 ``` // Object initializer. var instance3 = new ExampleClass { Name = "Desktop", ID = 37414, Location = "Redmond", Age = 2.3 }; // Default constructor and assignment statements. var instance4 = new ExampleClass(); instance4.Name = "Desktop"; instance4.ID = 37414; instance4.Location = "Redmond"; instance4.Age = 2.3; ``` ### 事件處理 * 如果你正定義一個稍后不需要刪除的事件處理程序，請使用 lambda 表達式。 ``` public Form2() { // You can use a lambda expression to define an event handler. this.Click += (s, e) => { MessageBox.Show( ((MouseEventArgs)e).Location.ToString()); }; } ``` ``` // Using a lambda expression shortens the following traditional definition. public Form1() { this.Click += new EventHandler(Form1_Click); } void Form1_Click(object sender, EventArgs e) { MessageBox.Show(((MouseEventArgs)e).Location.ToString()); } ``` ### 靜態成員 * 通過使用類名稱調用[靜態](https://msdn.microsoft.com/zh-CN/library/98f28cdx.aspx)成員：_ClassName.StaticMember_。這種做法通過明確靜態訪問使代碼更易于閱讀。請勿使用派生類的名稱限定基類中定義的靜態成員。編譯該代碼時，代碼可讀性具有誤導性，如果向派生類添加具有相同名稱的靜態成員，代碼可能會被破壞。 ### LINQ 查詢 * 對查詢變量使用有意義的名稱。下面的示例為位于西雅圖的客戶使用 seattleCustomers。 ``` var seattleCustomers = from cust in customers where cust.City == "Seattle" select cust.Name; ``` * 使用別名確保匿名類型的屬性名稱都使用 Pascal 大小寫格式正確大寫。 ``` var localDistributors = from customer in customers join distributor in distributors on customer.City equals distributor.City select new { Customer = customer, Distributor = distributor }; ``` * 如果結果中的屬性名稱模棱兩可，請對屬性重命名。例如，如果你的查詢返回客戶名稱和分銷商 ID，而不是在結果中將它們保留為 Name 和 ID，請對它們進行重命名以明確 Name 是客戶的名稱，ID 是分銷商的 ID。 ``` var localDistributors2 = from cust in customers join dist in distributors on cust.City equals dist.City select new { CustomerName = cust.Name, DistributorID = dist.ID }; ``` * 在查詢變量和范圍變量的聲明中使用隱式類型化。 ``` var seattleCustomers = from cust in customers where cust.City == "Seattle" select cust.Name; ``` * 對齊 [from](https://msdn.microsoft.com/zh-CN/library/bb383978.aspx) 子句下的查詢子句，如上面的示例所示。 * 在其他查詢子句之前使用 [where](https://msdn.microsoft.com/zh-CN/library/bb311043.aspx) 子句，以確保后面的查詢子句作用于經過減少和篩選的數據集。 ``` var seattleCustomers2 = from cust in customers where cust.City == "Seattle" orderby cust.Name select cust; ``` * 使用多行 **from** 子句代替 [join](https://msdn.microsoft.com/zh-CN/library/bb311040.aspx) 子句以訪問內部集合。例如，Student 對象的集合可能包含測驗分數的集合。當執行以下查詢時，它返回高于 90 的分數，并返回得到該分數的學生的姓氏。 ``` // Use a compound from to access the inner sequence within each element. var scoreQuery = from student in students from score in student.Scores where score > 90 select new { Last = student.LastName, score }; ``` ## 安全性請遵循[代碼安全維護指南](https://msdn.microsoft.com/zh-CN/library/8a3x2b7f.aspx)中的準則。 ## 請參閱 [Visual Basic 編碼約定](https://msdn.microsoft.com/zh-CN/library/h63fsef3.aspx) [代碼安全維護指南](https://msdn.microsoft.com/zh-CN/library/8a3x2b7f.aspx)