C# 编码规范

项目	注释哪些部分
参数	参数用来做什么任何约束或前提条件
字段/属性	字段描述
类	类的目的已知的问题类的开发/维护历史
接口	目的它应如何被使用以及如何不被使用
局部变量	用处/目的
成员函数注释	成员函数做什么以及它为什么做这个哪些参数必须传递给一个成员函数成员函数返回什么已知的问题任何由某个成员函数抛出的异常成员函数是如何改变对象的包含任何修改代码的历史如何在适当情况下调用成员函数的例子适用的前提条件和后置条件
成员函数内部注释	控制结构代码做了些什么以及为什么这样做局部变量难或复杂的代码处理顺序

5.4. 程序修改注释

Ö 新增代码行的前后要有注释行说明，对具体格式不作要求，但必须包含作者，新增时间，新增目的。在新增代码的最后必须加上结束标志；

Ö 删除代码行的前后要用注释行说明，删除代码用注释原有代码的方法。注释方法和内容同新增；删除的代码行建议用#region XXX #endregion 代码段折叠，保持代码文件干净整洁

Ö 修改代码行建议以删除代码行后再新增代码行的方式进行（针对别人的代码进行修改时，必须标明，对于自己的代码进行修改时，酌情进行）。注释方法和内容同新增；

6. 命名

6.1. 命名的基本约定

Ö 要使用可以准确说明变量/字段/类的完整的英文描述符，如firstName。对一些作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就可以被命名为 ” i ”。

Ö 要尽量采用项目所涉及领域的术语。

Ö 要采用大小写混合，提高名字的可读性。为区分一个标识符中的多个单词，把标识符中的每个单词的首字母大写。不采用下划线作分隔字符的写法。有两种适合的书写方法，适应于不同类型的标识符：

PasalCasing：标识符的第一个单词的字母大写；

camelCasing：标识符的第一个单词的字母小写。

下表描述了不同类型标识符的大小写规则：

标识符	大小写	示例
命名空间	Pascal	namespace Com.Techstar.ProductionCenter
类型	Pascal	public class DevsList
接口	Pascal	public interface ITableModel
方法	Pascal	public void UpdateData()
属性	Pascal	Public int Length{…}
事件	Pascal	public event EventHandler Changed;
私有字段	Camel	private string fieldName;
非私有字段	Pascal	public string FieldName；
枚举值	Pascal	FileMode{Append}
参数	Camel	public void UpdateData(string fieldName)
局部变量	Camel	string fieldName;

´ 避免使用缩写，如果一定要使用，就谨慎使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一致。

Ö 对常见缩略词，两个字母的缩写要采用统一大小写的方式（示例：ioStream，getIOStream）；多字母缩写采用首字母大写，其他字母小写的方式（示例：getHtmlTag）；

´ 避免使用长名字（最好不超过 15 个字母）。

´ 避免使用相似或者仅在大小写上有区别的名字。

6.2. 各种标示符类型的命名约定

6.2.1. 程序集命名

Ö 公司域名（Techstar）+ 项目名称 + 模块名称（可选），例如：

中心系统程序集：Techstar.ProductionCenter；

中心系统业务逻辑程序集：Techstar. ProductionCenter.Business；

6.2.2. 命名空间命名

Ö 采用和程序集命名相同的方式：公司域名（Techstar）+ 项目名称 + 模块名称。另外，一般情况下建议命名空间和目录结构相同。例如：

中心系统：Techstar.ProductionCenter；

中心系统下的用户控件：Techstar.ProductionCenter.UserControl；

中心系统业务逻辑：Techstar. ProductionCenter.Business；

中心系统数据访问：Techstar. ProductionCenter.Data；

6.2.3. 类和接口命名

Ö 类的名字要用名词；

´ 避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP。

Ö 接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个“I”前缀，例如对IComponent的标准实现为Component；

Ö 泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：

public class List<T>

public class MyClass<TSession>

´ 对同一项目的不同命名空间中的类，命名避免重复。避免引用时的冲突和混淆；

6.2.4. 方法命名

Ö 第一个单词一般是动词

Ö 如果方法返回一个成员变量的值，方法名一般为Get+成员变量名，如若返回的值是bool变量，一般以Is作为前缀。另外，如果必要，考虑用属性来替代方法，具体建议见10.1.2节;

Ö 如果方法修改一个成员变量的值，方法名一般为：Set + 成员变量名。同上，考虑用属性来替代方法；

6.2.5. 变量命名

Ö 按照使用范围来分，我们代码中的变量的基本上有以下几种类型，类的公有变量；类的私有变量（受保护同公有）；方法的参数变量；方法内部使用的局部变量。这些变量的命名规则基本相同，见标识符大小写对照表。区别如下：

i. 类的公有变量按通常的方式命名，无特殊要求；

ii. 类的私有变量采用两种方式均可：采用加“m”前缀，例如mWorkerName;

iii. 方法的参数变量采用camalString，例如workerName；

iv. 方法内部的局部变量采用camalString，例如workerName；

´ 不要用_或&作为第一个字母；

Ö 尽量要使用短而且具有意义的单词；

Ö 单字符的变量名一般只用于生命期非常短暂的变量。i,j,k,m,n一般用于integer；c,d,e 一般用于characters；s用于string

Ö 如果变量是集合，则变量名要用复数。例如表格的行数，命名应为：RowsCount；

Ö 命名组件要采用匈牙利命名法，所有前缀均应遵循同一个组件名称缩写列表

6.3. 组件名称缩写列表

缩写的基本原则是取组件类名各单词的第一个字母，如果只有一个单词，则去掉其中的元音，留下辅音。缩写全部为小写。

组件类型	缩写	例子
Label	Lbl	lblNote
TextBox	Txt	txtName
Button	Btn	btnOK
ImageButton	Ib	ibOK
LinkButton	Lb	lbJump
HyperLink	Hl	hlJump
DropDownList	Ddl	ddlList
CheckBox	Cb	cbChoice
CheckBoxList	Cbl	cblGroup
RadioButton	Rb	rbChoice
RadioButtonList	Rbl	rblGroup
Image	Img	imgBeauty
Panel	Pnl	pnlTree
TreeView	Tv	tvUnit
WebComTable	Wct	wctBasic
ImageDateTimeInput	Dti	dtiStart
ComboBox	Cb	cbList
MyImageButton	Mib	mibOK
WebComm.TreeView	Tv	tvUnit
PageBar	Pb	pbMaster

7. 声明

Ö 每行要只有一个声明，如果是声明i,j,k之类的简单变量可以放在一行;

Ö 除了for循环外，声明要放在块的最开始部分。for循环中的变量声明可以放在for语句中。如：for(int i = 0; I < 10; i++) 。

´ 避免块内部的变量与它外部的变量名相同。

8. 表达式和语句

Ö 每行建议只有一条语句。

Ö if-else,if-elseif语句，任何情况下，都应该有“{”，“}”，格式如下：

if (condition)

{

statements;

}

else if (condition)

{

statements;

}

else

{

statements;

}

Ö for语句格式如下：

for (initialization; condition; update)

{

statements;

}

如果语句为空：

for (initialization; condition; update) ;

Ö while语句格式如下：

while (condition)

{

statements;

}

如果语句为空:

while (condition);

Ö do-while语句格式如下：

{

statements;

}

while (condition);

Ö switch语句，每个switch里都应包含default子语句,格式如下：

switch (condition)

{

case ABC:

statements;

/* falls through */

case DEF:

statements;

break;

case XYZ:

statements;

break;

default:

statements;

break;

}

Ö try-catch语句格式如下：

try

{

statements;

}

catch (ExceptionClass e)

{

statements;

}

finally

{

statements;

}

9. 类型设计规范

Ö 要确保每个类型由一组定义明确，相互关联的成员组成，而不仅仅是一些无关功能的随机集合；

9.1. 类型和命名空间

Ö 要用命名空间把类型组织成相关域的层次结构。例如：

界面层：Techstar.ProductionCenter；

业务逻辑层：Techstar.ProductionCenter.Business；

数据访问层：Techstar.ProductionCenter.Data；

´ 避免过深的命名空间；

´ 避免太多的命名空间；

9.2. 类型和接口的选择

Ö 要优先采用类而不是接口。

接口的缺点在于语义变化时改变困难。注意接口并不是协定，把协定和实现分开并非一定用接口实现，用基类和抽象类同样可以表达；

Ö 建议使用抽象类而不是接口来解除协定与实现间的偶合；

Ö 要定义接口，来实现类似多重继承的效果；

精心定义接口的标志是一个接口只做一件事情。关键是接口的协定需要保持不变，如果一个接口包含太多功能，那么这个胖接口产生变化的机会就会大得多。

9.3. 抽象类设计：

´ 不要在抽象类中定义公有的或内部受保护的构造函数。因为抽象类无法实例化，所以这种设计会误导用户；

Ö 要为抽象类定义受保护的构造函数或内部构造函数；

9.4. 静态类设计

静态类是一个只包含静态成员的类，它提供了一种纯面向对象设计和简单性之间的一个权衡，广泛用来提供类似于全局变量或一些通用功能。

Ö 要少用静态类。静态类应该仅用作辅助类；

´ 避免把静态类当作杂物箱。每个静态类都应该有其明确目的；

Ö 不要在静态类中声明或覆盖实例成员；

9.5. 枚举设计

Ö 要用枚举来加强那些表示值的集合的参数，属性以及返回值的类型性；

Ö 要优先使用枚举而不是静态常量。例如：

//不好的写法

public static class Color

{

public static int Red = 0;

public static int Green = 1;

public static int Blue = 2;

}

//好的写法

public enum Color

{

Red,

Green,

Blue

}

´ 不要把枚举用于开放的场合，例如操作系统的版本，朋友的名字等；

´ 枚举最后一个值不要加逗号；

´ 枚举中不要提供为了今后使用而保留的枚举值；

10. 成员设计规范

方法，属性，事件，构造函数以及字段等统称为成员。

10.1. 成员设计的一般规范

10.2. 方法的重载规范；

´ 避免在重载中随意的给参数命名。如果两个重载中的某个参数表示相同的输入，那么该参数的名字应该相同。例如：

public class String

{

//好的写法

public int IndexOf(string value) { ...}

public int IndexOf(string value, int startIndex) { ...}

//不好的写法

public int IndexOf(string value) { ...}

public int IndexOf(string str, int startIndex) { ...}

}

´ 避免使重载成员的参数顺序不一致。在所有的重载中，同名参数应该出现在相同的位置。例如：

public class EventLog

{

public EventLog();

public EventLog(string logName);

public EventLog(string logName, string machineName);

public EventLog(string logName, string machineName, string source);

}

Ö 较短的重载应该仅仅调用较长的来实现。另外，重载如果需要扩展性，把最长重载做成虚函数。例如：

public class String

{

public int IndexOf(string s)

{

//调用

return IndexOf(s, 0);

}

public int IndexOf(string s, int startIndex)

{

//调用

return IndexOf(s, startIndex, s.Length);

}

public virtual int IndexOf(string s, int startIndex, int Count)

{

//实际的代码

}

Ö 要允许可选参选为null。这样做是为了避免调用者调用之前需要检查参数是否null。例如：

//允许为null时的调用

DrawGeometry(brush, pen, geometry);

//不允许为null时的调用

if (geometry == null) DrawGeometry(brush, pen);

else DrawGeometry(brush, pen, geometry);

10.3. 属性和方法的选择

Ö 基本原则是方法表示操作，属性表示数据。如果其他各方面都一样，优先使用属性而不是方法。

Ö 要使用属性，如果该成员表示类型的逻辑attribue

Ö 如果属性的值存储在内存中，而提供属性的目的仅仅是为了访问该值，要使用属性而不要使用方法

Ö 如果该操作每次返回的结果不同，那么要使用方法。例如来自于.net framework的例子:

//好的写法

Guid.NewGuid();

//不好的写法

DateTime.Now;

Ö 如果该操作比访问字段慢一个或多个数量级，要使用方法。

Ö 如果该操作有严重的副作用，要使用方法。

10.4. 属性的设计规范：

Ö 如果不应该让调用方法改变属性值，要创建只读属性；

´ 不要提供只写属性；

Ö 要为所有的属性提供合理的默认值，这样可以确保默认值不会导致漏洞或效率低的代码；

Ö 要允许用户以任何顺序来设置属性的值；

Ö 避免在属性的获取方法抛出异常。

属性的获取方法应该是个简单的操作，不应该有任何的条件。如果一个获取方法会抛出异常，按么可能它更应该设计为方法。

10.5. 构造函数的设计规范

Ö 建议提供简单的构造函数，最好是默认构造函数。简单的构造函数增强易用性；

Ö 考虑扩展性，如果构造函数设计的不自然，建议用静态的工厂方法来替代构造函数；

Ö 要把构造函数的参数用作设置主要属性的便捷方法。如果构造函数参数仅用来设置属性，应和属性名称相同。仅有大小写的区别；

Ö 要在构造函数中做最少的工作。任何其他处理应该推迟到需要的时候；

Ö 要在类中显示的声明公用的默认构造函数，如果这样的构造函数是必须的。

如果没有显示默认构造函数，填加有参数构造函数时往往会破坏已有使用默认构造函数的代码；

´ 避免在对象的构造函数内部调用虚成员。这样在扩展设计的时候会导致难以理解的现象；

10.6. 字段设计规范

´ 不要提供公有的或受保护的字段。代之以属性来访问字段；

Ö 要只用常量字段来表示永远不会改变的量。否则会导致兼容性问题。下面是正确的例子：

public struct Int32

{

public const int MaxValue = 0x7fffffff;

public const int MinValue = unchecked((int)0x80000000);

}

Ö 要用公有的静态只读字段来定义预定义的对象实例。例如：

public struct Color

{

public static readonly Color Red = new Color(0x0000FF);

}

10.7. 参数的设计规范

Ö 要用类结构层次中最接近基类类型来作为参数的类型，同时要保证该类型能够提供成员所需的功能。例如：

要设计一个集合遍历的方法，那么参数应该是IEnbumerable为参数，而不应该是IList，这样方法具有更强的适应性。

´ 不要使用保留参数。如果将来需要更多的参数，那么可以增加重载成员。例如：

//不好的写法

public void Method(string reserved, SomeOption option);

//好的写法

public void Method(SomeOption option);

//将来填加

public void Method(SomeOption option, string path);

10.7.1. 参数设计中枚举和布尔参数的选择规范

Ö 要用枚举。在代码阅读，书写中，枚举都比布尔的可读性好很多。例如：

//使用布尔型，阅读的时候不会轻易了解参数的含义

FileStream f = File.Open(“1.txt”, true, false);

//使用枚举型

FileStream f = File.Open(“1.txt”，CasingOptions.CaseSenstive, FileMode.Open);

´ 不要使用布尔参数，除非百分之百肯定绝对不需要两个以上的值。即使此时，采用枚举往往也可以提供更好的可读性，如上例。

Ö 考虑在构造函数中，对确实只有两种状态值的参数以及用来初始化布尔属性的参数使用布尔类型；

10.7.2. 参数验证的规范：

Ö 要验证传给公有的，受保护的或显示成员的参数是否合法。如果验证失败，应该抛出 System.ArgutmentException或其子类；

Ö 要抛出System.ArgutmentNullException，如果传入的null，而该成员不支持null；

10.7.3. 参数传递的规范：

´ 避免使用输出参数或引用参数；

11. 扩展性设计规范

´ 如果没有恰当理由，不要把类密封起来。这些理由包括：

A）类为静态类；

B）类的受保护成员保存了高度机密信息；

C）类继承了许多虚成员，逐个密封的代价太高，不如密封整个类；

D）不要在密封类中声明保护成员或虚成员，因为无法覆盖其实现；

Ö 建议用保护成员用于高级定制。它提供了扩展性，同时也避免了公用接口过于复杂；

´ 不要使用虚成员，除非有合适的理由；

Ö 建议只有在绝对必须的时候才用虚成员提供扩展性，并使用Template Method模式；

Ö 要优先使用受保护的虚成员，而不是公有虚成员。公有成员通用调用受保护的虚成员的方式来提供扩展性；

12. 异常处理规范

Ö 异常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。异常处理时可以采用适当的日志机制来报告异常，包括异常发生的时刻；

´ 一般情况下不要使用异常实现来控制程序流程结构；

´ 使用异常而不要用错误代码来报告错误；

Ö 要通过抛出异常的方式来报告操作失败。如果成员无法成功地完成它应该做的任务，那么应该抛出异常；

12.1. 异常类型选择规范

Ö 优先考虑使用System命名空间中已有的异常，而不是自己创建新的异常类型；

Ö 要使用最合理，最具针对性的异常。例如，对参数为空，应抛出 System.ArgutmentNullException，而不是System.ArgutmentException

12.2. 异常处理规范

´ 不是百分之百确定的情况，不要吞掉异常；

Ö 建议捕获特定类型的异常，如果理解该异常在具体环境当中产生的原因；

´ 不要捕获不应该捕获的异常，通常应该允许异常沿着调用栈传递；

Ö 进行清理工作时要用try-finally，避免使用try-catch；

Ö 要在捕获并重新抛出异常时使用空的throw语句，这是保持调用栈的最好方法

12.3. 标准异常类的使用：

12.3.1. Exception与SystemException

´ 不要抛出这两种类型的异常；

´ 避免捕获这两种异常，除非是在顶层的异常处理器中；

12.3.2. InvalidOperationException

Ö 对象处于不正确状态时抛出；

12.3.3. ArgumentException，ArgumentNullException，ArgumentOutOfRangeException

Ö 如果传入的是无效参数，要抛出参数异常，尽可能使用位于继承层次末尾的类型；

Ö 要在抛出异常时设置ParaName属性；

12.3.4. NullRefernceException，IndexOutOfRangeException，AccessViolationException

´ 不要显示抛出或捕获；

Ö 异常类要以“Exception”做为后缀；

Ö 要使异常可序列化，使其能跨应用程序域和远程边界仍能正常使用；

Ö 要把与安全性有关的信息保存在私有的异常状态中

12.5. 异常与性能

Ö 如果在普通场景都会抛出异常，要采用先效验合法性的方式来避免抛出异常引起的性能问题；

13. 其他规定

Ö 为避免频繁改动代码，代码中只写比较简单的和不会经常发生变化的SQL，如果SQL 经常发生变化或是比较复杂，存到SysMisc中，比如统计用到的SQL；

Ö 在VS2005开发环境中，采用代码分析工具来做自动化的代码分析，以保证代码质量，具体的使用建议如下：

A）启用代码分析，并设置当风格不符合要求时为错误而不是警告；

B）如果不是做代码审核，此开关应关闭。加上了这个选项的时候编译很慢；

C）详设的时候打开开关，检查详设是否符合编程规范；

D）所有的选项都应当打开。以下内容需要单独设置：

编码	名称	大类	建议	使用等级
CA2209	程序集应声明最小安全性	用法规则	不建议使用	警告
CA1814	与多维数组相比，首选使用交错的数组	性能规则	使用，但降低等级	警告
CA1822	将成员标记为 static	性能规则	较繁锁，且影响代码质量	禁用
CA2210	程序集应具有有效的强名称	设计规则	影响Xcopy部署	禁用
CA1302	不要对区域设置特定的字符串进行硬编码	全球化规则	很繁琐，并且工具支持的不好。全球化规则全部禁用	禁用
CA2100	检查 Sql 查询中是否有安全漏洞	安全性规则	都采用参数化查询，有可能会参数过长；如果是内部参数，也不会有安全问题	警告

14. 参考文档

1，《.NET设计规范》，本规范很多内容都参考了这本书，书中对规范背后的背景和原则做了深入讨论；

posted on 2009-10-15 19:20 冯瑞涛阅读(8616) 评论(12) 编辑收藏举报

刷新页面返回顶部

4.5. {”，“}”

6.3. 组件名称缩写列表

12.3.1. Exception与SystemException

12.3.3. ArgumentException，ArgumentNullException，ArgumentOutOfRangeException

12.3.4. NullRefernceException，IndexOutOfRangeException，AccessViolationException

12.3.5. StackOverflowException：

12.3.6. OutOfMemoryException：

公告