[译]C#编码约定
原文： https://msdn.microsoft.com/en-us/library/ff926074.aspx
编码约定的目的是：
-
创建统一格式的代码，让读者的注意力更集中在内容上面，而不是结构
-
让读者基于以前的经验能更快的理解代码
-
使得copy, 修改, 维护代码更加便利
-
演示C#最佳实践
命名约定
-
In short examples that do not include using directives, use namespace qualifications. If you know that a namespace is imported by default in a project, you do not have to fully qualify the names from that namespace. Qualified names can be broken after a dot (.) if they are too long for a single line, as shown in the following example.
var currentPerformanceCounterCategory = new System.Diagnostics. PerformanceCounterCategory();
- 不应该修改vs设计工具生成的对象的名字。
布局约定
好的布局格式化强调你代码的结构，让代码更易读。Microsoft的一些实例代码遵循下面的约定：
-
使用默认代码编辑器的设置 (smart缩进, 四个字符缩进, tab用空格代替)。详见Options, Text Editor, C#, Formatting。
-
一行只写一个语句。
-
一行只有一个声明的变量。
-
如果一个连续的行没有自动缩进，那么使用tab缩进 (4个空格)。
-
在方法的定义之间和属性定义之间至少添加一个空行。
-
使用括号把子表达式括起来，如下所示。
if ((val1 > val2) && (val1 > val3)) { // Take appropriate action. }
注释约定
-
在单独的一行添加注释，不要在代码的最后写注释。
-
注释文本以大写开头（首字母大写）。
-
注释文本以句号结尾。
-
注释符（//）和注释文本中留一个空格，如下所示。
// The following declaration creates a query. It does not run // the query.
- 不用星号多行注释。
语言指南
下面的章节展示了C#团队在写样例代码的时候所遵循的约定。
String Data Type
-
使用+号连接短字符串，如下所示。
string displayName = nameList[n].LastName + ", " + nameList[n].FirstName;
- 在循环里面append字符串的时候，特别是处理大文本的时候，使用StringBuilder对象。
var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala"; var manyPhrases = new StringBuilder(); for (var i = 0; i < 10000; i++) { manyPhrases.Append(phrase); } //Console.WriteLine("tra" + manyPhrases); 吐槽：微软的这个示例并没有遵循他自己在本文中说的//要和注释文本之间留一个空白
本地变量使用隐示类型
-
当变量的类型明显就是右边的表达式，或类型不是很重要的的时候使用 implicit typing。
// 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 。
[Author("P. Ackerman", version = 1.1)] class SampleClass
- 不要在变量名中包含变量的类型。
Author anonymousAuthorObject = new Author("P. Ackerman"); anonymousAuthorObject.version = 1.1;
- 不要对 dynamic使用var。
- 在for 和 foreach的循环参数中使用隐示类型。
var syllable = "ha"; var laugh = ""; for (var i = 0; i < 10; i++) { laugh += syllable; Console.WriteLine(laugh); }
foreach (var ch in laugh) { if (ch == 'h') Console.Write("H"); else Console.Write(ch); } Console.WriteLine();
Unsigned数据类型
-
通常不建议使用unsigned类型。
数组
-
使用简单的语法声明初始化数组。
// 推荐. 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.
Delegates
-
使用简单的语法创建委托实例。
// 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. // 推荐 Del exampleDel2 = DelMethod; // The following declaration uses the full syntax. Del exampleDel1 = new Del(DelMethod);
try-catch and using Statements in Exception Handling
-
Use a try-catch statement for most exception handling.
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; } }
- 使用using替代try finally。
// 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; }
&& and || Operators
-
使用&& 替代& 、||、 | 这样可以避免不必要的比较从而提高性能。
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(); - 使用对象初始化器来简单的创建对象。
// 对象初始化器. 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()); }
静态成员
-
Call static members by using the class name: ClassName.StaticMember. This practice makes code more readable by making static access clear. Do not qualify a static member defined in a base class with the name of a derived class. While that code compiles, the code readability is misleading, and the code may break in the future if you add a static member with the same name to the derived class.
LINQ查询
-
使用有意义的查询变量名。下面的实例使用seattleCustomers表示在Seattle的客户。
var seattleCustomers = from cust in customers where cust.City == "Seattle" select cust.Name; - 匿名类型的属性名使用Pascal casing。
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做为属性名，而是使用CustomerName和DistributorID。
var localDistributors2 = from cust in customers join dist in distributors on cust.City equals dist.City select new { CustomerName = cust.Name, DistributorID = dist.ID };
- 使用隐示变量声明query。
var seattleCustomers = from cust in customers where cust.City == "Seattle" select cust.Name;
- 查询子句和from对齐。
- Use where clauses before other query clauses to ensure that later query clauses operate on the reduced, filtered set of data.
var seattleCustomers2 = from cust in customers where cust.City == "Seattle" orderby cust.Name select cust;
- 使用多个from子句来代替join进入到内部关联。
// 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 };
