[译]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
.LastName + ", " + nameList
.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 };