C#编程规范

标签： C# 编程规范

---

命名规约

• 【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
• 【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
• 【强制】类名，方法名，属性，枚举名，接口名，委托，事件，命名空间，使用UpperCamelCase风格，必须遵从驼峰形式。通用缩写除外，如BO
• 【强制】参数名、成员变量、局部变量都统一使用lowerCamelCase 风格，必须遵从驼峰形式。如localValue
• 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。如MAX_STOCK_COUNT
• 【强制】抽象类命名使用Abstract或Base开头；异常类命名使用Exception结尾；测试类命名以它要测试的类的名称开始，以Test 结尾。
• 【强制】杜绝完全不规范的缩写，避免望文不知义。AbstractClass缩写命名成AbsClass；condition缩写命名成condi，此类随意缩写严重降低了代码的可阅读性。
• 【推荐】如果使用到了设计模式，建议在类名中体现出具体模式。如public class OrderFactory;

---

格式规约

• 【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则两个半括号都另起一行和类首对齐。
• 【强制】左小括号和右边相邻字符之间不出现空格；同样，右小括号和左边相邻字符之间也不出现空格。
• 【强制】if/for/while/switch/do等保留字与小括号之间都必须加空格。
• 【强制】任何运算符左右必须加一个空格。
• 【强制】缩进采用4个空格，禁止使用tab字符。或者在设置里面把tab设置为四个空格
• 【强制】单行字符数限制不超过120个，超出需要换行，换行时遵循如下原则：
  1） 第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进，参考示例。
  2） 运算符与下文一起换行。
  3） 方法调用的点符号与下文一起换行。
  4） 在多个参数超长，逗号后进行换行。
  5） 在括号前不要换行。
• 【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。
• 【强制】IDE 的text file encoding设置为UTF-8;IDE中文件的换行符使用Unix格式，不要使用windows格式。
• 【推荐】没有必要增加若干空格来使某一行的字符与上一行的相应字符对齐。
• 【推荐】方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。

---

OOP 规约

• 【强制】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。
• 【强制】所有的相同类型的包装类对象之间值的比较，全部使用Equals方法比较。
• 【强制】构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在Init方法中。。
• 【推荐】使用索引访问用String的Split方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛IndexOutOfBoundsException的风险。
• 【推荐】当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读。
• 【推荐】 类内方法定义顺序依次是：公有方法或保护方法 > 属性 > 私有方法。
• 【推荐】循环体内，字符串的连接方式，使用StringBuilder的append方法进行扩展。
• 【推荐】类成员与方法访问控制从严：
  1） 如果不允许外部直接通过new来创建对象，那么构造方法必须是private。
  2） 工具类不允许有public或default构造方法。
  3） 类非static成员变量并且与子类共享，必须是protected。
  4） 类非static成员变量并且仅在本类使用，必须是private。
  5） 类static成员变量如果仅在本类使用，必须是private。
  6） 若是static成员变量，必须考虑是否为final。
  7） 类成员方法只供类内部调用，必须是private。
  8） 类成员方法只对继承类公开，那么限制为protected。

---

控制语句

• 【强制】在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有。
• 在if/else/for/while/do语句中必须使用大括号。即使只有一行代码，避免使用单行的形式
• 【推荐】表达异常的分支时，少用if-else方式，这种方式可以改写成：

if (condition) 
{
    ...
    return obj;
}
// 接着写else的业务逻辑代码;

• 【推荐】除常用方法（如getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
• 【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的try-catch操作（这个try-catch是否可以移至循环体外）。
• 【参考】下列情形，需要进行参数校验：
  1） 调用频次低的方法。
  2） 执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
  3） 需要极高稳定性和可用性的方法。
  4） 对外提供的开放接口，不管是RPC/API/HTTP接口。
  5） 敏感权限入口。
• 【参考】下列情形，不需要进行参数校验：
  1） 极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。
  2） 底层调用频度比较高的方法。
  3） 被声明成private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

---

注释规约

• 【强制】所有的类都必须添加创建者和创建日期。
• 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
• 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。
• 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
• 【参考】合理处理注释掉的代码。尽量在目标代码上方详细说明，而不是简单的注释掉。如果无用，则直接删除。
• 【参考】对于注释的要求：
  第一、能够准确反应设计思想和代码逻辑；
  第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
• 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

---

参考资料

[1] 阿里巴巴java开发手册
[2] C#标准命名规范