目 录
使用.net进行开发的过程中遵循的基本规范。
1. 命名原则
编码中的命名规范和原则
1.1 大小写原则
目前存在不同的大小写规范,下面列出的这些规范将在其后的章节反复引用。
l Pascal Casing
每个单词的第一个字母大写,例如:BackColor
l Camel Casing
除了第一个单词以外的每个单词的第一个字母大写,例如:backColor
l Upper case
如果缩写字母的个数小于或等于2,那么所有的缩写字母都大写。3个以上的字母缩写采用Pascal Casing。例如:System.IO, System.Web.UI, System.CodeDom。
1.2 命名规范
类型 | 命名规范 | 备注 |
Class | PascalCase |
|
Enum values | PascalCase |
|
Enum type | PascalCase |
|
Events | PascalCase |
|
Exception class | PascalCase | 以 Exception结尾 |
Final Static field | PascalCase |
|
interface | PascalCase | 用大写字母 I开头 |
Method | PascalCase |
|
Namespace | PascalCase |
|
property | PascalCase |
|
Public Instance Field | PascalCase | 很少使用, 用在properties |
Protected Instances Fields | camelCase | 很少使用, 用在properties |
parameter | camelCase |
|
1.3 类的命名原则
l 用pascal命名规则
l 尽量谨慎的使用缩写
l 尽量不要使用任何的前缀(例如C,T)
l 不要用下划线作类名
例如:
Public class FileStream
{
}
Public class Button
{
}
Public class String
{
}
1.4 接口命名原则
l 接口名字用名词或者名词短语,或形容词来表述接口的行为。
例如:IComponent (描述性名词)、ICustomAttributeProvider (名词短语)、IPersistable (形容词)等。
l 用Pascal 命名规则
l 尽量谨慎地使用缩写
l 不要用下划线作类名
l 接口名称前缀用字母I
有的时候, 必须用字母I作为类名前缀,而又不是一个接口。这是可以接受的,因为有的类名就是I开头的,例如: IdentityStore。这种情况和接口的区别在于其第二个字母是小写的。
有的时候,定义完一个接口之后,也会定义一个类作为接口的标准实现。该类和该接口应该有类似的名字,唯一的区别就是接口名称前缀为字母I。
下面的例子描述了接口 IComponent 和它的标准实现- 类 Component
Public interface IComponent
{
}
Public class Component :IComponent
{
}
1.5 Exception命名原则
异常的命名以“Exception”为后缀,且继承自平台提供的异常基类PlatformBaseException,例如:
Public class UserAlreadyExistsException : PlatformBaseException
{
}
1.6 参数的命名
l 参数的名字应该是描述性的
参数的名字应该具有自描述性,也就是说参数的名称可以描述参数在大多数情况下的含义,参数的类型也是可以从参数的名字推断出来的。
l 参数的名字使用camel Casing(首字母小写)
l 参数的名字是基于参数的含义而不是参数的类型
l 不要使用保留参数(Win32 API常见)
如果下一个版本需要更多的参数,那么加一个overload的方法。
参数的命名示例如下:
Type GetType(string typeName)
String Format(string format, object[] args)
1.7 变量的命名
避免无意义的变量命名,如下的命名应该避免:
Contract a = new Contract();
但以下情况除外,作为循环条件中的计数器:
for ( int i = 0; i < MaxNum; i++)
1.8 方法命名原则
l 用动词或动词短语来命名
l 用Pascal命名约定
方法的命名示例如下:
RemoveAll()
Char[] GetCharArray()
1.9 属性命名原则
l 属性名称使用名词或名词短语
l 用Pascal命名约定
l 可以考虑用类型名称作为属性名称
属性的命名示例如下:
Public Color Color
{
Get{}
Set{}
}
1.10 大小写敏感
l 不要出现必须要大小写敏感支持的名字.组件,应该在无论大小写敏感或不敏感的语言中都能使用。因为需要大小写敏感的语言不能识别两个相同内容但用大小写区分的名字,所以组件必须避免这种情况
l 不要出现两个只用大小写区分的命名空间,如
namespace ee.cummings;
namespace Ee.Cummings;
l 不要出现两个只用大小写区分的参数如.
void foo(string a, string A)
l 不要出现只用大小写区分的同一命名空间的类型
System.WinForms.Point p;
System.WinForms.POINT pp;
l 不要出现只用大小写区分的同一类型属性。
int Foo {get, set};
int FOO {get, set}
l 不要出现两个只用大小写区分的方法
void foo();
void Foo();
2. 注释
2.1 注释通用原则
原则上平均每100行代码中要有20~30行注释,视程序复杂程度而定。
所有注释应使用中文。
对于源文件和类,必须在注释中说明修改历史。
2.2 类和接口的注释
采用微软.Net提供的格式,具体内容如下:
/// <summary>
/// <see cref="IUserManager"/>接口定义了<see cref="User"/>实体类的增、删、改、读
/// (CRUD)方法,该接口的实现类将负责用户对象的简单管理。
/// </summary>
/// <remarks>
/// <see cref="IUserManager"/>接口仅定义<see cref="User"/>实体对象的CRUD操作方法,
/// 并没有定义关联用户对象与群组、组织机构等的操作,这些业务逻辑操作的方法定义在
/// 专门的关联操作接口<see cref="IUserGroupAssociator"/>及<see cref="IUserOrgAssociator"/>中。
/// </remarks>
/// Title: IUserManager
/// Copyright: ***** Software LTD.co Copyright (c) 2006
/// Company: *****有限公司
/// Designer: ***
/// Coder: 姜辉
/// Reviewer:
/// Tester: ***
/// Version: 1.0
/// History:
/// 2006-07-14 姜辉 [创建]
/// 2006-07-15 姜辉 [编码]
/// 2006-08-10 姜辉 [修改] 根据外部用户需要,包装GetUserNameById()WEB服务方法.
在<summary>中填写类的简要描述,<remarks>中填写类的一些注意事项。Histroy填写修改记录。
所有类和接口都要注释。类的操作注释由详细设计产物导出,编程人员补充完成从Title到History的部分。
2.3 类成员变量的注释
类成员变量的注释如下例所示:
/// <summary>
/// 用户的名称
/// </summary>
private string username;
在声明前,利用.Net的格式来注释,原则上类的成员变量都要注释。
2.4 方法的注释
方法的注释如下例所示:
/// <summary>
/// 根据指定的用户登录名、姓名及密码创建(注册)一个新用户(<see cref="User"/>)。
/// </summary>
/// <remarks>
/// 当满足如下任意情形之一时,创建用户的操作将会失败:
/// 1,指定的用户名在用户持久化存储中已存在
/// 2,指定的用户名不合法(空值,空字符串,多个空格,包含除字母及数字以外的非法字符,长度
/// 超过64)
/// 3,指定的用户密码不合法(空值,空字符串,多个空格,包含除字母及数字以外的非法字符,长
/// 度小于6位或大于位64)
/// 4,指定的用户姓名不合法(空值,空字符串,多个空格,长度大于位64)
/// </remarks>
/// <param name="loginName">用户的登录名,该属性必须唯一,如“zhangsan”</param>
/// <param name="username">用户的名称,该属性可以重复,如多个用户均可以叫“张三”</param>
/// <param name="password">用户登录的密码</param>
/// <returns>创建的新用户对象(<see cref="User"/>)</returns>
/// <exception cref="UserAlreadyExistsException">用户已经存在时所抛出的异常</exception>
/// <exception cref="InvalidLoginNameException">用户登录名不合法时所抛出的异常/exception>
/// <exception cref="InvalidUsernameException">用户姓名不合法时所抛出的异常</exception>
/// <exception cref="InvalidPasswordException">用户登录密码不合法时所抛出的异常<exception>
User CreateUser(string loginName, string username, string password);
<summary>中填写该方法的主要功能描述,<remarks>中填写该方法的注意事项,<param>中填写方法的传入参数,以及各参数的意义。<returns> 填写函数返回值以及返回值的意义。注意在其中运用xml语法。
所有的public及protected方法都要注释。.net2.0下public若无注释会报警告信息。
2.5 程序中的注释
在程序中,采用 ”//”进行单行注释。
所有程序中的分支语句需要注释分支条件意义,循环语句需要注释循环的起始条件和中止条件。
// 满足支付条件
if (MeetPayCondition())
…
// 循环遍历数组
for ( int i = 0; i < Array.Count; i++ )
…
3. 其他通用规范
3.1 关于修改历史
在每一个程序单元(一个C#文件或一个VB.NET文件)中记录本程序单元的修改历史,修改历史包括日期,修改者,修改动作。
/// History:
/// 2006-07-14 姜辉 [创建]
/// 2006-10-9 张冠南 [修改] 根据同行评审结果进行修改
3.2 成对出现的关键字和”{}”的使用
相关联的“{“和”}”要么处于同一行,要么处于同一列。
3.3 规则缩进
用”TAB”和空格处理缩进,相当于4个空格长度,用空格替代制表符。
3.4 判断和循环的注释
对于大段的(超过20行)判断、循环语句,要加注释,对于判断语句(如if,switch),要说明判断的条件和程序的走向。对于循环语句(如while,do while,for),要说明循环继续和终止的条件。
3.5 缩写
一个项目中用到的同一词语的缩写要求完全统一,如”Project”缩写为”PJT”,则不准用其它的缩写,如”Prjt”或”Pjct”,并且区分大小写,即”pjt”也不能再用于表示”Project”。
3.6 关于汉语拼音
尽量不要使用汉语拼音的声母缩写来做命名。如”Py”用来表示”拼音”会有很多的歧义。
3.7 关于神秘的数字
无论用何种语言编程,都不要出现神秘的数字,如下代码应视为违反本规范:
int n;
n = 128;
…
对于程序中要用到的常数,在专门的文件中进行定义,定义方法统一用大写的英文,例如:
public final int FILE_NAME_MAX_LENTH = 128;…
也可以写入到独立的配置文件中,在程序中读出其中的数值。
如果仅仅是某个类中所使用的话,就作为常量写入类中,例如:
private const string SIGN_STATUS = “ 50” ;
对于数据类型为int型的这些常量,尽量使用枚举类型来处理这些神秘数字。
在程序中的数字也并不一定属于神秘的数字,以下情况是允许的:
1, 索引数字,比如数组访问,数据库字段读取dataReader.GetString(2);
2, 单元测试代码中用到的数字。
控件Id的命名采取camel大小写,建议规则如下:
控件类型 | 名称前缀 | 样例 |
TextBox | txt | txtDraftId |
DropDownList | ddl | ddlDraftStatus |
Button | btn | btnAuditProject |
MultiView | mvw | mvwMultiPage |
View | viw | viwPageOne |
LinkButton | lbn | lbnCreateDraftForm |
GridView | gvw | gvwDeviceGridWiew |
Label | lbl | lblCurrentPage |
Menu | meu | meuTab |
TreeView | tvw | tvwOrganization |
CheckBox | cbx | cbxCheck |
CheckBoxList | cbl | cblChecks |
ImageButton | ibn | ibnCreateDraftForm |
Image | img | imgPicture |
HyperLink | hlk | hlkPageLink |
ListBox | lbx | lbxPersons |
RadioButton | rbn | rbnChoiceOne |
RadioButtonList | rbl | rblChoices |
FileUpload | fud | fudChooseFile |
Panal | pal | palEdit |
DataList | dlt | dltEdit |
DetailsView | dvw | dvwRetrieve |
RequiredFieldValidator | rfv | rfvNameValidator |
RangeValidator | rvd | rvdAge |
RegularExpressionValidator | rev | revTelephone |
CompareValidator | cmv | cmvCompareValue |
CustomValidator | cuv | cuvValidator |
ValidationSummary | vds | vdsSummary |