C# 编码约定(C# 编程指南)C# Coding Conventions (C# Programming Guide)

编码约定可实现以下目的:Coding conventions serve the following purposes:

  • 它们为代码创建一致的外观,以确保读取器专注于内容而非布局。They create a consistent look to the code, so that readers can focus on content, not layout.

  • 它们使得读取器可以通过基于之前的经验进行的假设更快地理解代码。They enable readers to understand the code more quickly by making assumptions based on previous experience.

  • 它们便于复制、更改和维护代码。They facilitate copying, changing, and maintaining the code.

  • 它们展示 C# 最佳做法。They demonstrate C# best practices.

Microsoft 根据本文中的准则来开发样本和文档。The guidelines in this article are used by Microsoft to develop samples and documentation.

命名约定Naming Conventions

  • 在不包括 using 指令的短示例中,使用命名空间限定。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();
    
  • 你不必更改通过使用 Visual Studio 设计器工具创建的对象的名称以使它们适合其他准则。You do not have to change the names of objects that were created by using the Visual Studio designer tools to make them fit other guidelines.

布局约定Layout Conventions

好的布局利用格式设置来强调代码的结构并使代码更便于阅读。Good layout uses formatting to emphasize the structure of your code and to make the code easier to read. Microsoft 示例和样本符合以下约定:Microsoft examples and samples conform to the following conventions:

  • 使用默认的代码编辑器设置(智能缩进、4 字符缩进、制表符保存为空格)。Use the default Code Editor settings (smart indenting, four-character indents, tabs saved as spaces). 有关详细信息,请参阅选项、文本编辑器、C#、格式设置For more information, see Options, Text Editor, C#, Formatting.

  • 每行只写一条语句。Write only one statement per line.

  • 每行只写一个声明。Write only one declaration per line.

  • 如果连续行未自动缩进,请将它们缩进一个制表符位(四个空格)。If continuation lines are not indented automatically, indent them one tab stop (four spaces).

  • 在方法定义与属性定义之间添加至少一个空白行。Add at least one blank line between method definitions and property definitions.

  • 使用括号突出表达式中的子句,如下面的代码所示。Use parentheses to make clauses in an expression apparent, as shown in the following code.

    if ((val1 > val2) && (val1 > val3))
    {
        // Take appropriate action.
    }
    

注释约定Commenting Conventions

  • 将注释放在单独的行上,而非代码行的末尾。Place the comment on a separate line, not at the end of a line of code.

  • 以大写字母开始注释文本。Begin comment text with an uppercase letter.

  • 以句点结束注释文本。End comment text with a period.

  • 在注释分隔符 (//) 与注释文本之间插入一个空格,如下面的示例所示。Insert one space between the comment delimiter (//) and the comment text, as shown in the following example.

    // The following declaration creates a query. It does not run
    // the query.
    
  • 不要在注释周围创建格式化的星号块。Do not create formatted blocks of asterisks around comments.

语言准则Language Guidelines

以下各节介绍 C# 遵循以准备代码示例和样本的做法。The following sections describe practices that the C# team follows to prepare code examples and samples.

String 数据类型String Data Type

  • 使用字符串内插来连接短字符串,如下面的代码所示。Use string interpolation to concatenate short strings, as shown in the following code.

    string displayName = $"{nameList[n].LastName}, {nameList[n].FirstName}";
    
  • 若要在循环中追加字符串,尤其是在使用大量文本时,请使用 StringBuilder 对象。To append strings in loops, especially when you are working with large amounts of text, use a StringBuilder object.

    var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala";
    var manyPhrases = new StringBuilder();
    for (var i = 0; i < 10000; i++)
    {
        manyPhrases.Append(phrase);
    }
    //Console.WriteLine("tra" + manyPhrases);
    

隐式类型的局部变量Implicitly Typed Local Variables

  • 当变量类型明显来自赋值的右侧时,或者当精度类型不重要时,请对本地变量进行隐式类型化Use implicit typing for local variables when the type of the variable is obvious from the right side of the assignment, or when the precise type is not important.

    // 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());
    
  • 当类型并非明显来自赋值的右侧时,请勿使用 varDo not use var when the type is not apparent from the right side of the assignment.

    // When the type of a variable is not clear from the context, use an
    // explicit type.
    int var4 = ExampleClass.ResultSoFar();
    
  • 请勿依靠变量名称来指定变量的类型。Do not rely on the variable name to specify the type of the variable. 它可能不正确。It might not be correct.

    // Naming the following variable inputInt is misleading.
    // It is a string.
    var inputInt = Console.ReadLine();
    Console.WriteLine(inputInt);
    
  • 避免使用 var 来代替 dynamicAvoid the use of var in place of dynamic.

  • 使用隐式类型化来确定 for 循环中循环变量的类型。Use implicit typing to determine the type of the loop variable in for loops.

    下面的示例在 for 语句中使用隐式类型化。The following example uses implicit typing in a for statement.

    var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala";
    var manyPhrases = new StringBuilder();
    for (var i = 0; i < 10000; i++)
    {
        manyPhrases.Append(phrase);
    }
    //Console.WriteLine("tra" + manyPhrases);
    
  • 不要使用隐式类型化来确定 foreach 循环中循环变量的类型。Do not use implicit typing to determine the type of the loop variable in foreach loops.

    下面的示例在 foreach 语句中使用显式类型化。The following example uses explicit typing in a foreach statement.

    foreach (char ch in laugh)
    {
        if (ch == 'h')
            Console.Write("H");
        else
            Console.Write(ch);
    }
    Console.WriteLine();
    

    备注

    注意不要意外更改可迭代集合的元素类型。Be careful not to accidentally change a type of an element of the iterable collection. 例如,在 foreach 语句中从 System.Linq.IQueryable 切换到 System.Collections.IEnumerable 很容易,这会更改查询的执行。For example, it is easy to switch from System.Linq.IQueryable to System.Collections.IEnumerable in a foreach statement, which changes the execution of a query.

无符号数据类型Unsigned Data Type

通常,使用 int 而非无符号类型。In general, use int rather than unsigned types. int 的使用在整个 C# 中都很常见,并且当你使用 int 时,更易于与其他库交互。The use of int is common throughout C#, and it is easier to interact with other libraries when you use int.

阵列Arrays

当在声明行上初始化数组时,请使用简洁的语法。Use the concise syntax when you initialize arrays on the declaration line.

// 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.

委托Delegates

使用简洁的语法来创建委托类型的实例。Use the concise syntax to create instances of a delegate type.

// 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 and using Statements in Exception Handling

  • 对大多数异常处理使用 try-catch 语句。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;
        }
    }
    
  • 通过使用 C# using 语句简化你的代码。Simplify your code by using the C# using statement. 如果具有 try-finally 语句(该语句中 finally 块的唯一代码是对 Dispose 方法的调用),请使用 using 语句代替。If you have a try-finally statement in which the only code in the finally block is a call to the Dispose method, use a using statement instead.

    // 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

若要通过跳过不必要的比较来避免异常并提高性能,请在执行比较时使用 &&(而不是 &),使用 || (而不是 |),如下面的示例所示。To avoid exceptions and increase performance by skipping unnecessary comparisons, use && instead of & and || instead of | when you perform comparisons, as shown in the following example.

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 运算符New Operator

  • 隐式类型化时,请使用对象实例化的简洁形式,如下面的声明所示。Use the concise form of object instantiation, with implicit typing, as shown in the following declaration.

    var instance1 = new ExampleClass();
    

    上一行等同于下面的声明。The previous line is equivalent to the following declaration.

    ExampleClass instance2 = new ExampleClass();
    
  • 使用对象初始值设定项来简化对象创建。Use object initializers to simplify object creation.

    // 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;
    

事件处理Event Handling

如果你正定义一个稍后不需要删除的事件处理程序,请使用 lambda 表达式。If you are defining an event handler that you do not need to remove later, use a lambda expression.

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());
}

静态成员Static Members

通过使用类名称调用静态成员:ClassName.StaticMember。 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 查询LINQ Queries

  • 对查询变量使用有意义的名称。Use meaningful names for query variables. 下面的示例为位于西雅图的客户使用 seattleCustomersThe following example uses seattleCustomers for customers who are located in Seattle.

    var seattleCustomers = from customer in customers
                           where customer.City == "Seattle"
                           select customer.Name;
    
  • 使用别名确保匿名类型的属性名称都使用 Pascal 大小写格式正确大写。Use aliases to make sure that property names of anonymous types are correctly capitalized, using Pascal casing.

    var localDistributors =
        from customer in customers
        join distributor in distributors on customer.City equals distributor.City
        select new { Customer = customer, Distributor = distributor };
    
  • 如果结果中的属性名称模棱两可,请对属性重命名。Rename properties when the property names in the result would be ambiguous. 例如,如果你的查询返回客户名称和分销商 ID,而不是在结果中将它们保留为 NameID,请对它们进行重命名以明确 Name 是客户的名称,ID 是分销商的 ID。For example, if your query returns a customer name and a distributor ID, instead of leaving them as Name and ID in the result, rename them to clarify that Name is the name of a customer, and ID is the ID of a distributor.

    var localDistributors2 =
        from customer in customers
        join distributor in distributors on customer.City equals distributor.City
        select new { CustomerName = customer.Name, DistributorID = distributor.ID };
    
  • 在查询变量和范围变量的声明中使用隐式类型化。Use implicit typing in the declaration of query variables and range variables.

    var seattleCustomers = from customer in customers
                           where customer.City == "Seattle"
                           select customer.Name;
    
  • 对齐 from 子句下的查询子句,如上面的示例所示。Align query clauses under the from clause, as shown in the previous examples.

  • 在其他查询子句之前使用 where 子句,以确保后面的查询子句作用于经过减少和筛选的数据集。Use where clauses before other query clauses to ensure that later query clauses operate on the reduced, filtered set of data.

    var seattleCustomers2 = from customer in customers
                            where customer.City == "Seattle"
                            orderby customer.Name
                            select customer;
    
  • 使用多行 from 子句代替 join 子句以访问内部集合。Use multiple from clauses instead of a join clause to access inner collections. 例如,Student 对象的集合可能包含测验分数的集合。For example, a collection of Student objects might each contain a collection of test scores. 当执行以下查询时,它返回高于 90 的分数,并返回得到该分数的学生的姓氏。When the following query is executed, it returns each score that is over 90, along with the last name of the student who received the score.

    // 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 };
    

安全Security

请遵循安全编码准则中的准则。Follow the guidelines in Secure Coding Guidelines.

另请参阅See also