C-编程规范.doc

C#编码规范

注:C－创建;　M－修改; D－删除; A－添加

1 目的

为了保证企业编写出的程序都符合相同的规范，保证一致性、统一性而建立的程序编码规范。
编码规范对于程序员而言尤为重要，有以下几个原因：
- 一个软件的生命周期中，80%的花费在于维护
- 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护
- 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码
- 如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品
为了执行规范，每个软件开发人员必须一致遵守编码规范。每个人。

2 范围

适用于企业所有基于C#.NET平台的软件开发工作。
3 规范内容
3.1 文件规范
3.1.1 文件命名与类名名称相同
3.1.2 文件内容格式
开头注释
引用
命名空间
类体
变量(代理事件)：用#region 变量………#endregion包括
属性：用#region属性………#endregion包括
构造：
方法(事件的实现)：用#region方法………#endregion包括
3.2 代码格式
所有的缩进为4个空格，以空格代替Tab 。选中”插入空格(P)”
在代码中垂直对齐左括号和右括号。
if(x==0)
{
Response.Write("用户编号必须输入！");
}
不允许以下情况：
if(x==0) {

Response.Write("用户编号必须输入！");
}
或者：
if(x==0){ Response.Write("用户编号必须输入！");}

为了防止在阅读代码时不得不滚动源代码编辑器，每行代码或注释在1024*800的显示频率下不得超过一显示屏
当一行被分为几行时，通过将串联运算符放在每一行的末尾而不是开头，清楚地表示没有后面的行是不完整的。
每一行上放置的语句避免超过一条。
在大多数运算符之前和之后使用空格，这样做时不会改变代码的意图却可以使代码容易阅读。
例：
int j = i + k;
而不应写为
int j=i+k;
将大的复杂代码节分为较小的、易于理解的模块。
编写 SQL 语句时，对于关键字使用全部大写，对于数据库元素（如表、列和视图）使用大小写混合。
将每个主要的 SQL 子句放在不同的行上，这样更容易阅读和编辑语句，例如：
SELECT FirstName, LastName
FROM Customers
WHERE State = 'WA'

3.3 注释（Comment）规范

注释规范包括：模块（类）注释规范、类的属性、方法注释规范、代码间注释
3.3.1 模块（类）注释规范
模块开始必须以以下形式书写模块注释：
///<summary>
///定义某某类的方法
///</summary>
///<see cref="Author">作者 </see>
///<see cref="Email">email@e- </see>
///<see cref="Data">2003-12-17</see>
如果模块有修改，则每次修改必须添加以下注释：
///<remark>备注版本修改信息，修改了那些，时间，每次依次增加remark</remark>
3.3.2 类属性注释规范
在类的属性必须以以下格式编写属性注释：
/// <summary>
///属性说明
/// </summary>
3.3.3 方法注释规范
在类的方法声明前必须以以下格式编写注释
/// <summary>
/// 说明：<对该方法的说明>
/// </summary>
/// <param name="<参数名称>"><参数说明></param>
/// <returns> /<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义>
/// </returns>

3.3.4 代码间注释规范
代码间注释分为单行注释和多行注释：
单行注释：
//<单行注释>
多行注释：
/*多行注释1
多行注释2
多行注释3*/
代码中遇到语句块时必须添加注释（if,for,foreach,……）,添加的注释必须能够说明此语句块的作用和实现手段（所用算法等等）。

3.4 变量（Variable）命名规范
3.4.1 程序文件(*.cs)中的变量命名规则
程序中变量名称 = 变量的前缀 +代表变量含意的英文单词或单词缩写。

1． 类模块级的变量类型的缩写作前缀
public class hello
{
private string s_Name;
private DateTime dt_Date;

}
2． 类的属性所对应的变量，采用属性名前加类型的缩写作前缀前缀的形式
public class hello
{
private string s_Name;
public string Name
{
get
{
return m_Name;
}
}
}
3． 过程级的变量不使用前缀
public class hello
{
void say()
{
string SayWord;
}
}
4． 过程的参数使用“p_”作为参数
public class hello
{
void say(string p_SayWord)
{
}
}

补充说明：
针对异常捕获过程中的Exception变量命名，在没有冲突的情况下，统一命名为e；
如果有冲突的情况下，可以重复e，比如：ee。
Try
{
//your code
try
{
//code
}
catch(Exception ee)
{
//your code
}
}
catch(Exception e)
{
//your code
}
补充：如果捕获异常不需要作任何处理，则不需要定义Exception实例
例：
try
{
//your code
}
catch( Exception )
{
}

5． 鉴于大多数名称都是通过连接若干单词构造的，请使用大小写混合的格式以简化它们的阅读。每个单词的第一个字母都是大写.
6． 即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。
7． 在变量名中使用互补对，如 min/max、begin/end 和 open/close。
8． 不要使用原义数字或原义字符串，如 for( i = 1,i< 7;i++)。而是使用命名常数，如 for( i = 1,i< NUM_DAYS_IN_WEEK ; i++) 以便于维护和理解。

3.4.2 控件命名规则
控件命名=Web控件缩写前缀 + “_” +变量名
控件 缩写
Label
lbl

TextBox
txt

CheckBox
chk

Button
cmd

ListBox
lst

DropDownList
drp

等等

3.4.3 常量命名规范

常量名也应当有一定的意义，格式为 NOUN 或 NOUN_VERB。常量名均为大写，字之间用下划线分隔。
例：
private const bool WEB_ENABLEPAGECACHE_DEFAULT = true;
private const int WEB_PAGECACHEEXPIRESINSECONDS_DEFAULT = 3600;
private const bool WEB_ENABLESSL_DEFAULT = false;

注：
变量名和常量名最多可以包含 255 个字符，但是，超过 25 到 30 个字符的名称比较笨拙。此外，要想取一个有实际意义的名称，清楚地表达变量或常量的用途，25 或 30 个字符应当足够了。

3.4.4 类（Class）命名规范

1． 名字应该能够标识事物的特性。
2． 名字尽量不使用缩写，除非它是众所周知的。
3． 名字可以有两个或三个单词组成，但通常不应多于三个。
4． 在名字中，所有单词第一个字母大写，缩写都要大写。
例如 IsSuperUser，包含ID的，ID全部大写，如CustomerID。
5． 使用名词或名词短语命名类。
6． 少用缩写。
7． 不要使用下划线字符 (_)。
例：
public class FileStream
public class Button
public class String

3.4.5 接口（Interface）命名规范

和类命名规范相同，唯一区别是 接口在名字前加上“I”前缀
例：
interface IDBCommand;
interface IButton;

3.4.6 方法（Method）命名规范

和类命名规范相同。
另：方法开头尽量使用e文动词表示，
如：GetMoney , SetMoney
3.4.7 命名空间（NameSpace）命名规范

和类命名规范相同。

4 实施建议

先对编码人员进行“专题”培训，让他们掌握此编码规则。
系统设计人员、编码人员、测试人员可以较好的建议，适当地修改完善

C#编程规范

1适用范围

本标准适用于利用Visul C# ,其余语言作参考.。

2变量命名

命名必须具有一定的实际意义,形式为xAbcFgh,x由变量类型确定,Abc、Fgh表示连续意
义字符串,如果连续意义字符串仅两个,可都大写.如OK.

具体例程:

BOOL类型 bEnable;

sz char szText

sb sbyte sbText

bt byte btText

n int nText

ui uint uiText

l long lText

ul ulong ulText

f float fText

d double dText

b bool bText

de decimal deText

str string strText

x,y 坐标

att 表属性

m_ 类成员变量 m_nVal, m_bFlag

s_ 类静态成员变量 s_nVal,s_bFlag

//不提议用全局变量,其于类的实例,尽量选取表示该类特性的字母,例如classText,class体现类的特性.

3常量命名和宏定义

常量和宏定义必须具有一定的实际意义;

常量和宏定义在#include和函数定义之间;

常量和宏定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一
条定义的右侧必须有一简单的注释,说明其作用;

4资源名字定义格式(我对.NET的资源还没有了解的多),只写几个:
菜单:IDM_XX或者CM_XX
位图:IDB_XX
对话框:IDD_XX
字符串:IDS_XX
DLGINIT:DIALOG_XX
ICON:IDR_XX

5函数命名和命名空间,类的命名,接口的命名
函数原型说明包括引用外来函数及内部函数，外部引用必须在右侧注明函数来源： 模
块名及文件名, 如是内部函数，只要注释其定义文件名;
第一个字母必须使用大写字母,要求用大小写字母组合规范函数命名,必要时可用下划线
间隔,示例如下：

void PrintTrackData ( );

void ShowChar (int , int ,char);

事件函数的命名:

void EventH(object sd,Event e) //Event 表示事件响应的函数.

接口的命名

接口的命名一般都以’I’作为首字母,为了和类区分,例如:

interface IA

命名空间(例如 namespace A)和类的命名规则从原则上和函数命名相同.

6结构体命名
结构体类型命名必须全部用大写字母,原则上前面以下划线开始;结构体变量命名必须用
大小写字母组合，第一个字母必须使用大写字母,必要时可用下划线间隔。对于私有数
据区，必须注明其所属的进程。全局数据定义只需注意其用途。

示例如下：
typedef struct
{
char szProductName[20];
char szAuthor[20];
char szReleaseDate[16];
char szVersion[10];
unsigned long MaxTables;
unsigned long UsedTables;
}DBS_DATABASE;
DBS_DATABASE GdataBase;

7 控件的命名：

C#控件规则为了和.net类库统一,分WindowsForm程序和Web程序(也许大家不是很习惯J).

WindowsForm程序

用小写前缀表示类别

fm 窗口
cmd 按钮
cob combo，下拉式列表框
txt 文本输入框
lab labal，标签
img image，图象
pic picture
grd Grid，网格
scr 滚动条
lst 列表框
frm fram

Web程序

用大写前缀表示类别

Fm 窗口
Cmd 按钮
Cob combo，下拉式列表框
Txt 文本输入框
Lab labal，标签
Img image，图象
Pic picture
Grd Grid，网格
Scr 滚动条
Lst 列表框
Frm fram

8注释

原则上注释要求使用中文;
文件开始注释内容包括:公司名称、版权、作者名称、时间、模块用途、背景介绍等,复
杂的算法需要加上流程说明;
函数注释包括:输入、输出、函数描述、流程处理、全局变量、调用样例等,复杂的函数
需要加上变量用途说明;
程序中注释包括:修改时间和作者、方便理解的注释等;
引用一: 文件开头的注释模板
/******************************************************************
** 文件名:
** Copyright (c) 1998-1999 *********公司技术开发部
** 创建人:
** 日 期:
** 修改人:
** 日 期:
** 描 述:
**
** 版 本:
**----------------------------------------------------------------------------
******************************************************************/

引用二: 函数开头的注释模板
/*****************************************************************
** 函数名:
** 输 入: a,b,c
** a---
** b---
** c---
** 输 出: x---
** x 为 1, 表示...
** x 为 0, 表示...
** 功能描述:
** 全局变量:
** 调用模块:
** 作 者:
** 日 期:
** 修 改:
** 日 期:
** 版本
****************************************************************/
引用三: 程序中的注释模板
/*----------------------------------------------------------*/
/* 注释内容 */
/*----------------------------------------------------------*/

9 程序
a. 程序编码力求简洁，结构清晰，避免太多的分支结构及太过于技巧性的程序，
尽量不采用递归模式。
b. 编写程序时，亦必须想好测试的方法，换句话说，”单元测试” 的测试方案应
在程序编写时一并拟好。
c. 注释一定要与程序一致。
d. 版本封存以后的修改一定要将老语句用/* */ 封闭，不能自行删除或修改,并要
在文件及函数的修改记录中加以记录。
e. 程序中每个block 的开头 ”{" 及 "}” 必须对齐，嵌套的block 每进一套，
缩进一个tab，TAB 为4个空格,block类型包括if、for、while、do等关键字引出的。
f. 对于比较大的函数，每个block 和特殊的函数调用，都必须注明其功能.

C#编程规范

1. 避免将多个类放在一个文件里面。

2. 一个文件应该只有一个命名空间，避免将多个命名空间放在同一个文件里面。

3. 一个文件最好不要超过500行的代码（不包括IDE产生的代码）。

4. 一个方法的代码长度最好不要超过25行。

5. 避免方法中有超过5个参数的情况。如果超过了，则应使用 struct 来传递多个参数。

6. 每行代码不要超过80个字符。

7. 原则上，尽量不要手工的修改机器产生的代码。
　　a) 如果需要编辑机器（IDE）产生的代码，编辑格式和风格要符合该编码标准。
　　b) 尽可能地使用片断类来把被保持的部分分解为各个因素
　　 注：这里的翻译参考了灵感之源老兄的说法，在Visual c#2005中，C#的语法已经支持partial修饰符，它的作用是可以将一个完整的类分解各个部分类，在编译时，编译器会将它们构造为一个类。
　　具体请参考

8. 避免利用注释解释显而易见的代码。
　　a) 代码应该可以自解释。好的代码本身就应具体良好的可读性，所使用的变量和方法命名一般情况下不需要注释。

9. 文档应该仅用于assumptions, algorithm insights等等.

10. 避免使用方法级的文档。
　　a) 使用扩展的API文档进行说明。
　　b) 只有在该方法需要被其他的开发者使用的时候才使用方法级的注释。（在C#中就是///）

11. 不要硬编码数字的值，总是使用构造函数设定其值。

12. 只有是自然结构才能直接使用const(常量)，比如一个星期的天数。

13. 区别只读变量及常量的使用方法，如果想实现只读变量，可以直接使用readonly 修饰符。
　　public class MyClass
　　{
　　public readonly int Number;
　　public MyClass(int someValue)
　　{
　　　　Number = someValue;
　　}
　　public const int DaysInWeek = 7;
　　}

14. 每个假设必须使用Assert检查
　　a) 平均每15行要有一次检查(Assert)
　　using System.Diagnostics;
　　object GetObject()
　　{…}
　　object obj = GetObject();
　　Debug.Assert(obj != null);

15. 代码的每一行都应该通过白盒方式的测试。

16. 只抛出已经显示处理的异常。

17. 在捕获(catch)语句的抛出异常子句中(throw)，总是抛出原始异常，用以维护原始错误的堆栈分配。
　　catch(Exception exception)
　　{
　　　　MessageBox.Show(exception.Message);
　　　　throw ; //和throw exception一样。
　　}
　　注：同理，不推荐在循环语句中，进行直接的return操作。
　　for (int i=0;i<100;i++)
　　 {
　　　　 if (i==10)
　　　　 {
　　　　　　 return; //不推荐的方式
　　　　}
　　}

18. 避免方法的返回值是错误代码。

19. 尽量避免定义自定义异常类。

20. 当需要定义自定义的异常时：
　　a) 自定义异常要继承于ApplicationException。
　　b) 提供自定义的序列化功能。

21. 避免在单个程序集里使用多个Main方法。

22. 只对外公布必要的操作，其他的则为internal。

23. 避免使用友元程序集，因为它会增加程序集间的耦合度。

24. 避免编写从指定的位置加载的程序集的代码。

25. 使应用程序集尽量为最小化代码(EXE客户程序)。使用类库来替换包含的商务逻辑。

26. 避免给枚举变量提供显式的值。
　　//正确方法
　　public enum Color
　　{
　　　　Red,Green,Blue
　　}
　　//避免
　　public enum Color
　　{
　　　　Red = 1,Green = 2,Blue = 3
　　}

27. 避免指定特殊类型的枚举变量。
//避免
　　public enum Color : long
　　{
　　　　Red,Green,Blue
　　}

28. 即使if语句只有一句，也要将if语句的内容用大括号扩起来。

29. 避免使用trinary条件操作符。

30. 避免在条件语句中调用返回bool值的函数。可以使用局部变量并检查这些局部变量。
　　bool IsEverythingOK()
　　{…}
//避免
　　if (IsEverythingOK ())
　　{…}
//替换方案
　　bool ok = IsEverythingOK();
　　if (ok)
　　{…}

31. 总是使用基于0开始的数组。

32. 在循环中总是显式的初始化引用类型的数组。
　　public class MyClass
　　{}
　　MyClass[] array = new MyClass[100];
　　for(int index = 0; index < array.Length; index++)
　　{
　　　　array[index] = new MyClass();
　　}

33. 尽量不要提供public 和 protected的成员变量，使用属性代替他们。

34. 避免在继承中使用new而使用override来进行替换。

35. 在不是sealed的类中总是将public 和 protected的方法标记成virtual的。

36. 除非使用interop(COM+ 或其他的dll)代码否则不要使用不安全的代码(unsafe code)。

37. 避免显式的转换，使用as操作符进行兼容类型的转换。
　　Dog dog = new GermanShepherd();
　　GermanShepherd shepherd = dog as GermanShepherd;
　　if (shepherd != null )
　　{…}

38. 当类成员包括委托的时候
　　a) 在调用委托前，将它拷贝到一个本地变量中，用以避免并发争用条件。
　　b) 在调用委托之前一定要检查它是否为null
　　public class MySource
　　{
　　　　public event EventHandler MyEvent;
　　　　public void FireEvent()
　　　　{
　　　　　　//将委托拷到一个本地变量中。
　　　　　　EventHandler temp = MyEvent;
　　　　　　//确定它是否为空?
　　　　　　if(temp != null )
　　　　　　{
　　　　　　　　temp(this,EventArgs.Empty);
　　　　　　}
　　　　}
　　}

39. 不要提供公共的事件成员变量，使用事件访问器替换这些变量。
　　public class MySource
　　{
　　　　MyDelegate m_SomeEvent ;
　　　　public event MyDelegate SomeEvent
　　　　{
　　　　　　add
　　　　　　{
　　　　　　　　m_SomeEvent += value;
　　　　　　}
　　　　　　　　remove
　　　　　　{
　　　　　　　　m_SomeEvent -= value;
　　　　　　}
　　　　}
　　}

40. 使用一个事件帮助类来公布事件的定义。

41. 总是使用接口。

42. 类和接口中的方法和属性至少为2:1的比例。

43. 避免一个接口中只有一个成员。

44. 尽量使每个接口中包含3－5个成员。

45. 接口中的成员不应该超过20个。
　　a) 根据实际情况可能限制为12个

46. 避免接口成员中包含事件。

47. 避免使用抽象方法而使用接口替换。

48. 在类层次中显示接口。

49. 推荐使用显式的接口实现。

50. 从不假设一个类型兼容一个接口，并应防止查询那些接口。
　　SomeType obj1;
　　IMyInterface obj2;

　　/* 假设已有代码初始化过obj1，接下来 */
　　obj2 = obj1 as IMyInterface;
　　if (obj2 != null)
　　{
　　　　obj2.Method1();
　　}
　　else
　　{
　　　　//处理错误
　　}

51. 表现给最终用户的字符串（一般指UI界面中的部分）不要使用直接编码，而应该要使用资源文件来替换。
注：这样做的目的是方便软件的本地化。

52. 不要直接编写可能会更改的基于配置的字符串，比如连接字符串。

53. 当需要构建较长的字符串的时候，应该考虑使用StringBuilder不要使用string来处理。
注：string每次要创建一个新的实例，较占用空间，并产生了相对StringBuilder更大的性能消耗。对于过于频繁的字符串操作，采用StringBuilder是一个良好的习惯。

54. 避免在结构里面提供方法。
　　a) 建议使用参数化构造函数
　　b) 可以重载操作符

55. 总是要给静态变量提供静态构造函数。

56. 在能够使用早期绑定的情况下，尽量避免使用后期绑定。
　　 注：后期绑定虽然灵活，但带来的不仅仅是性能上的消耗，更多的是编码上的复杂性和混乱的逻辑。

57. 使用应用程序的日志和跟踪。

58. 除非在不完全的switch语句中否则不要使用goto语句。
注：原则上不应使用goto语句，除非在能够大大减轻编码的复杂性，并不影响可读性的前提下才允许使用。

59. 在switch语句中总是要有default子句来显示信息(Assert)。
　　int number = SomeMethod();
　　switch(number)
　　{
　　　　case 1:
　　　　　　Trace.WriteLine("Case 1:");
　　　　　　break;
　　　　case 2:
　　　　　　Trace.WriteLine("Case 2:");
　　　　　　break;
　　　　default :
　　　　　　Debug.Assert(false);
　　　　　　break;
　　}

60. 除非在构造函数中调用其他构造函数否则不要使用this指针。
　　// 正确使用this的例子
　　public class MyClass
　　{
　　　　public MyClass(string message )
　　　　{}
　　　　public MyClass() : this("hello")
　　　　{}
　　}

61. 除非你想重写子类中存在名称冲突的成员或者调用基类的构造函数否则不要使用base来访问基类的成员。
　　// 正确使用base的例子
　　public class Dog
　　{
　　　　public Dog(string name)
　　　　{}
　　　　virtual public void Bark( int howLong)
　　　　{}
　　}
　　public class GermanShepherd : Dog
　　{
　　　　public GermanShe pherd(string name): base (name)
　　　　{}
　　　　override public void Bark(int howLong)
　　　　{
　　　　　　base .Bark(howLong);
　　　　}
　　}

62. 基于模板的时候要实现Dispose()和Finalize()两个方法。

63. 通常情况下避免有从System.Object转换来和由System.Object转换去的代码，而使用强制转换或者as操作符替换。
　　class SomeClass
　　{}
　　//避免：
　　class MyClass<T>
　　{
　　　　void SomeMethod(T t)
　　　　{
　　　　　　object temp = t;
　　　　　　SomeClass obj = (SomeClass)temp;
　　　　}
　　}
　　// 正确：
　　class MyClass<T> where T : SomeClass
　　{
　　　　void SomeMethod(T t)
　　　　{
　　　　　　SomeClass obj = t;
　　　　}
　　}

64. 在一般情况下不要定义有限制符的接口。接口的限制级别通常可以用强类型来替换之。
　　public class Customer
　　{…}
　　//避免：
　　public interface IList<T> where T : Customer
　　{…}
　　//正确：
　　public interface ICustomerList : IList<Customer>
　　{…}

65. 不确定在接口内的具体方法的限制条件。

66. 总是选择使用C#内置（一般的generics）的数据结构

67、初始化类的实例时，除非十分必要，否则不要赋null值。

68、使用后的实例，尽量不要将该实例的引用赋值和为nul，尤其是采用public来修饰的类成员l。
　　1）如果该实例是临时引用，请使用using语句，然后在程序块中使用。
　　2）如果需要释放资源，应可能地使用Dispose，采用null值的方法，该引用在指向下一个实例前，不会被回收。