【.NET Core】常见C#代码约定

一、概述

代码标准对于在开发团队中维护代码可读性、一致性和协作至关重要。 遵循行业实践和既定准则的代码更易于理解、维护和扩展。 大多数项目通过代码约定强制要求样式一致。本文我们将讨论编码约定和用于强制实施这些约定的工具。

二、代码预定的目标

• 正确性

在编辑代码时，需要代码具有复原能力且正确无误，即使在多次编辑之后也是如此。

• 一致性

在编写代码中，我们需要遵循相同的规则，使之在整个项目周期中遵循相同的规则样式。

三、代码约束工具和分析器

工具可帮助团队强制实施标准。可以启用代码分析来强制实施代码规则。可以创建editorconfig,以便Visual Studio可自动强制实施样式标准。

借助这些工具，团队可以更轻松地采用首选的标准。Visual Studio将在范围中的所有.editorconfig文件中应用规则，以设置代码的格式。可以使用多个配置来强制实施企业范围的标准、团队标准甚至精细的项目标准。

启用的规则被违反时，代码分析会生成警告和诊断。可以配置想要应用于项目的规则。然后，每个CI生成会在违反任何规则时通知开发人员。

四、C#语言准则

一般情况C#需要遵从以下准则：

• 尽可能利用新式语言功能和 C# 版本
• 避免陈旧或过时的语言构造
• 仅捕获可以正确处理的异常；避免捕获泛型异常
• 使用特定的异常类型提供有意义的错误消息
• 使用 LINQ 查询和方法进行集合操作，以提高代码可读性
• 将异步编程与异步和等待用于 I/O 绑定操作
• 谨慎处理死锁状态，并在适当时使用Task.ConfigureAwait
• 对数据类型而不是运行时类型使用语言关键字。例如：定义字符串使用string而不是System.String，或使用int而不是System.Int32
• 使用 int 而不是无符号类型。 int 的使用在整个 C# 中很常见，并且当你使用 int 时，更易于与其他库交互。 特定于无符号数据类型的文档例外
• 仅当读者可以从表达式推断类型时使用 var
• 以简洁明晰的方式编写代码
• 避免过于复杂和费解的代码逻辑

五、字符串约定

5.1 使用字符串内插来连接短字符串

string displayName = $"{JsonList[n].LastName}, {JsonList[n].FirstName}";

5.2 插入大文本时，使用System.Text.StringBuilder对象

var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala";
var manyPhrases = new StringBuilder();
for (var i = 0; i < 10000; i++)
{manyPhrases.Append(phrase);
}
var response = stringBuilder.ToString();

六、数组约定

• 当在声明行上初始化数组时，请使用简洁的语法

string[] vowels1 = { "H", "O", "O", "L", "G" };

• 如果使用显式实例化，则可以使用 var

var word=new String[]{"G","O","Y","E","E","R"};

七、委托约定

7.1 使用Func<>和Action<>，而不是定义委托类型

Action<string> actionExample1 = x => Console.WriteLine($"x is: {x}");
Action<string, string> actionExample2 = (x, y) =>Console.WriteLine($"x is: {x}, y is {y}");
Func<string, int> funcExample1 = x => Convert.ToInt32(x);
Func<int, int, int> funcExample2 = (x, y) => x + y;

7.2 使用Func<>和Action<>委托定义的签名来调用方法

actionExample1("string for x");
actionExample2("string for x", "string for y");
Console.WriteLine($"The value is {funcExample1("1")}");
Console.WriteLine($"The sum is {funcExample2(1, 2)}");

7.3 如果创建委托类型的实例，请使用简洁的语法

public delegate void Del(string message);
public static void DelMethod(string str)
{Console.WriteLine("DelMethod argument: {0}", str);
}

7.4 创建委托类型的实例，然后调用该实例

Del exampleDel2 = DelMethod;
exampleDel2("Hey");

八、&& 和 || 运算符

8.1 在执行比较时，使用&& 而不是 &，使用||而不是|

Console.Write("Enter a dividend: ");
int dividend = Convert.ToInt32(Console.ReadLine());
Console.Write("Enter a divisor: ");
int divisor = Convert.ToInt32(Console.ReadLine());
if ((divisor != 0) && (dividend / divisor) is var result)
{Console.WriteLine("Quotient: {0}", result);
}
else
{Console.WriteLine("Attempted division by 0 ends up here.");
}

九、new运算符

9.1 使用对象实例化的简洁形式

var firstExample = new ExampleClass();
ExampleClass instance2 = new();

前面的声明等效于下面的声明：

ExampleClass secondExample = new ExampleClass();

9.2 使用对象初始值设定项简化对象创建

var thirdExample = new ExampleClass { Name = "Desktop", ID = 37414,Location = "Redmond", Age = 2.3 };

十、静态成员

使用类名调用static成员：ClassName.StaticMember。通过明确静态访问使代码更易于阅读。请勿使用派生类的名称来限定基类中定义的静态成员。编译代码时，代码可读性具有误导性，如果向派生类添加具有相同名称的静态成员，代码可能会被破坏。

十一、LINQ查询

11.1 对查询变量使用有意义的名称

var seattleCustomers = from customer in customerswhere customer.City == "Seattle"select customer.Name;

11.2 使用别名确保匿名类型的属性名称都使用 Pascal 大小写格式正确大写

var localDistributors =from customer in customersjoin distributor in distributors on customer.City equals distributor.Cityselect new { Customer = customer, Distributor = distributor };

11.3 如果结果中的属性名称模棱两可，请对属性重命名

var localDistributors2 =from customer in customersjoin distributor in distributors on customer.City equals distributor.Cityselect new { CustomerName = customer.Name, DistributorID = distributor.ID };

11.4 在查询变量和范围变量的声明中使用隐式类型化

var seattleCustomers = from customer in customerswhere customer.City == "Seattle"select customer.Name;

11.5 对齐from子句下的查询子句，其他查询子句前面使用where子句，确保后面的查询子句作用于作用于经过缩减和筛选的一组数据

var seattleCustomers2 = from customer in customerswhere customer.City == "Seattle"orderby customer.Nameselect customer;

11.6 使用多行 from 子句代替join子句来访问内部集合

var scoreQuery = from student in studentsfrom score in student.Scores!where score > 90select new { Last = student.LastName, score };

十二、隐式类型本地变量

12.1 当变量的类型在赋值右侧比较明显时，对局部变量使用隐式类型

var message = "This is clearly a string.";
var currentTemperature = 27;

12.2 当类型在赋值右侧不明显时，请勿使用var

int numberOfIterations = Convert.ToInt32(Console.ReadLine());
int currentMaximum = ExampleClass.ResultSoFar();

12.3 不要使用变量名称指定变量的类型

12.4 避免使用var来替代dynamic

如果想要进行运行时类型推理，请使用 dynamic

12.5 在for循环中对循环变量使用隐式类型

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

12.6 不要使用隐式类型在foreach循环中类型

不要使用隐式类型化来确定 foreach循环中循环变量的类型。 在大多数情况下，集合中的元素类型并不明显。 不应仅依靠集合的名称来推断其元素的类型。

12.7 对 LINQ 查询中的结果序列使用隐式类型

关于LINQ的部分说明了许多LINQ查询会导致必须使用隐式类型的匿名类型。其他查询则会产生嵌套泛型类型，其中var的可读性更高。

十三、注释样式

• 使用单行注释（//）以进行简要说明
• 避免使用多行注释（/* */）来进行较长的解释。 注释不进行本地化处理。 相反，配套文章中提供了较长的解释
• 若要描述方法、类、字段和所有公共成员，请使用XML注释
• 将注释放在单独的行上，而非代码行的末尾
• 以大写字母开始注释文本
• 以句点结束注释文本
• 在注释分隔符 (//) 与注释文本之间插入一个空格