大玩家队——代码规范

[big_players]

这个作业属于哪个课程	2302软件工程
这个作业要求在哪里	团队作业—bate冲刺+事后诸葛亮
团队名称	大玩家队
这个作业的目标	制定代码规范
参考文献	C#编码规范——阿里云开发者社区

目录

• 1、命名规范
• 驼峰命名法(camelCasing)
• 2、布局规范
• 3、注释规范
• 4、代码规范/语言准则
• 4.1 字符串数据类型
• 4.2 隐式类型本地变量
• 4.3 无符号数据类型
• 4.4 数组
• 4.5 委托
• 4.6 异常处理
• 4.7 && 和 || 运算符
• 4.8 new 运算符 使用对象初始化值设定简化对象创建
• 4.9 事件处理
• 4.10 静态成员
• 4.11 OOP面向对象规约
• 4.12 控制语句

1、命名规范

驼峰命名法(camelCasing)

1.命名private或internal字段时使用驼峰命名，且字段名应以_开头。

2.如果是static的private或internal的字段，则字段名应该以s_开头，对于线程静态则应该使用t_开头。

3.编写方法的参数名时，也应该以驼峰命名。

2、布局规范

1.使用默认的代码编辑器设置（智能缩进、4 字符缩进、制表符保存为空格）。

2.每行只写一条语句。

3.每行只写一个声明。

4.C# 的大括号采用的是Allman style，大括号单独一行。

5.如果连续行未自动缩进，请将它们缩进一个制表符位（四个空格）。

6.在方法定义与属性定义之间添加至少一个空白行。

7.使用括号突出表达式中的子句。

8.if / for / while / switch / do 等保留字与左右括号之间都必须加空格。

9.任何运算符左右必须加一个空格。

说明：运算符包括赋值运算符 = 、逻辑运算符&&、加减乘除符号、三目运算符等。

10.方法参数在定义和传入时，多个参数逗号后必须加空格。

3、注释规范

1.将注释放在单独的行上，而非代码行的末尾。

2.类方法的注释必须使用C# Summary 规范，以大写字母开始注释文本。

说明：在vs中，Summary方式会提示相关的注释，生成Summary可以正确输出相应的注释。工程调用方法是，不进入方法，即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

3.以句点结束注释文本。

4.在注释分隔符 (//) 与注释文本之间插入一个空格。

5.请勿在注释周围创建格式化的星号块。

6.请确保所有公共成员Public都有必要的注释，从而提供有关其行为的适当说明。

7.所有的抽象方法（包括接口中的方法）必须使用Summary注释，除了返回值、参数、异常说明外，还必须指出该方法做了什么事，实现了什么功能。

说明：对于子类的实现要求，或者调用注意事项，请一并说明。

8.方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释使用 /* */ 注释，注意与代码对齐。

9.语气 “ 半吊子 ” 英文来注释，不如用中文注释把问题说清楚。但专有名字与关键字保持英文原文即可。

反例： “ TCP连接超时 ” 解释成 “ 传输控制协议连接超时 ” ，理解反而费脑筋。

10.代码修改的同事，注释也要进行相应的修改，预期是参数、返回值、异常、核心逻辑等的修改。

11.注释掉的代码尽可能而配合说明，而不是简单的注释掉

说明：代码被注释掉有两种可能性：

1）后续会恢复此段代码逻辑。

2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。

12.对于注释的要求：

1）能够准确反应设计思想和代码逻辑；

2）能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。

说明：完全没有注释的大段代码，对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能够清晰理解当时的思路；

注释也是给继任者看的，使其能够快读接替自己的工作。

13.好的命名、代码结构是自解释的，注释力求精简准确，表达到位。

避免出现注释的一个极端：过多滥的注释，代码逻辑一旦修改，修改注释是相当大的负担。

14.特殊注释标记，请注明标记人与标记时间。

注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

1）待办事宜（TODO）：（标记人、标记时间，[预计处理时间]）表示需要实现，但目前还未实现的功能。

4、代码规范/语言准则

4.1 字符串数据类型

1.使用字符串内插来连接短字符串。

2.若要在循环中追加字符串，尤其是在使用大量文本时，请使用 StringBuilder 对象。

4.2 隐式类型本地变量

1.当变量类型明显来自赋值的右侧时，或者当精度类型不重要时，请对本地变量进行隐式类型化。

2.当类型并非明显来自赋值的右侧时，请勿使用 var。 请勿假设类型明显来自方法名称。 如果变量类型为 new 运算符或显式强制转换，则将其视为明显来自方法名称。

3.请勿依靠变量名称来指定变量的类型。 它可能不正确。 在以下示例中，变量名称 inputInt 会产生误导性。 它是字符串。

4.使用隐式类型化来确定 for 循环中循环变量的类型。

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

4.3 无符号数据类型

通常，使用 int 而非无符号类型。 int 的使用在整个 C# 中都很常见，并且当你使用 int 时，更易于与其他库交互。

4.4 数组

1.当在声明行上初始化数组时，请使用简洁的语法。 在以下示例中，请注意不能使用 var 替代 string[] 。

string[] xiaoY = { "x", "i", "a", "o", "Y" };

2.如果使用显式实例化，则可以使用 var。

var xiaoY = new string[] { "x", "i", "a", "o", "Y" };

4.5 委托

1.在用到委托时尽量使用 Func<> 和 Action<>，而不是自定义委托类型。 在类中，定义委托方法。

2.如果创建委托类型的实例，请使用简洁的语法。 在类中，定义委托类型和具有匹配签名的方法。

3.创建委托类型的实例，然后调用该实例。

1） 以下声明显示了紧缩的语法。

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

2）以下声明使用了完整的语法。

Del exampleDel1 = new Del(DelMethod);
exampleDel1("Hey xiaoY");

4.6 异常处理

1.try-catch 和 using 语句正在异常处理中

1）在平时使用异常处理时一般都使用 try-catch 语句。我们可以使用 using 来简化代码，简化资源的Dispose。

2）如果具有 try-finally语句（该语句中 finally 块的唯一代码是对 Dispose 方法的调用），可使用 using 语句代替。

2.异常不要用来做流程控制，条件控制。因为异常的处理效率比条件分支低。

3.大段代码进行try-catch，这是不负责任的表现。catch时请分清稳定代码合肥稳定代码，稳定代码指的是无论如何都不会出错的代码。对于费稳定代码的catch尽量可能的进行区分异常类型，再做对应的异常处理。

4.捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，就将该异常抛给他的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

5.有try块放到了事务代码中，catch异常后，如果要回滚事务，一定要注意手动回滚事务。

6.finally块必须对资源对象、流对象进行关闭，有异常也要做tyr-catch。

7.捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。

说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。

8.方法的返回值可以是null，不强制返回空集合或空对象等，必须添加注释充分说明什么情况下会返回null值。调用方进行null判断，防止NRE空引用异常问题（NullReferenceException）。

4.7 && 和 || 运算符

1.若要通过跳过不必要的比较来避免异常并提高性能，请在执行比较时使用 &&（而不是 &）和 ||（而不是 |）。

2.当第一个表达式为 false 时，&& 运算符将发生短路。 也就是说，它并不评估第二个表达式。 如果 divisor 为 0，则 & 运算符将同时计算这两个表达式，这会导致运行时错误。

4.8 new 运算符 使用对象初始化值设定简化对象创建

使用对象初始值设定项简化对象创建，如以下示例中所示。

var student1 = new ExampleClass { Name = "xioaY", ID = 001,
    sex = "man", Age = 24 };

4.9 事件处理

如果正在定义一个稍后不需要删除的事件处理程序，请使用 lambda 表达式。

4.10 静态成员

使用类名调用 static 成员：ClassName.StaticMember。

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

4.11 OOP面向对象规约

1.避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。

2.不能使用过时的类或方法（[Obsolate]标识）

说明：C#中对于标记过时的方法，有可能会在新版本的.Net Framework中剔除，因此不建议继续使用此类或方法。

3.Object 的Equals方法容易抛空引用异常，应使用常量或确定有值得对象来调用Equals。

        //反例
        "XiaoY".Equals(gameObject.tag);
        //正例
        gameObject.tag.Equals("XiaoY");

4.构造方法中禁止加入业务逻辑，如有初始化逻辑等，请放在Init() 方法中。

5.当一个类有多个构造方法，或多个同名方法，这些方法应该按照顺序放置在一起，便于阅读。

6.类内方法定义顺序依次是：常量、字段、属性、方法，按照public -> protected -> private 排序。

7.类成员与方法访问控制从严

1）如果不允许外部直接通过new来创建对象，那么构造方法必须是private。

2）工具类不允许有public或default构造方法。

3）类非static成员变量并且与子类共享，必须是protected。

4）类非static成员变量并且仅在本类使用，必须是private。

5）类static成员变量如果仅在本类使用，必须是private。

6）类成员方法只供内部调用，必须是private。

7）类成员方法只对继承类公开，那么限制为protected。

说明：任何类、方法、参数、变量，严控访问范围，过宽泛的访问范围，不利于模块解耦。如果一个private的方法，想删除就删除，可是一个public的Service方法，或者一个public的成员变量，删除一下，造成的损失可能没办法完全掌控。所以在一开始创建该类时就应该将访问明码标价，防止后期出现其他问题。

4.12 控制语句

1.在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止：在一个switch块内，都必须包含一个default语句，并且放在最后，即使它什么代码都没有。

2.在 if / else / for / while / do 语句中都必须使用大括号，即使只有一行代码，避免使用下面的形式： if (condition) do something…

3.循环体内的语句要考虑性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接。