[译]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 };