一、目的
为了统一公司软件开发的设计过程中关于代码编写时的编写规范和具体开发工作时的编程规范,保证代码的一致性,便于交流和维护,特制定此规范。
二 、注释
(1)自建代码文件
对于自己创建的代码文件(如函数、脚本),在文件开头,一般编写如下注释:
/*************************************************
作者:
小组:
说明:
创建日期:
版本号:
**********************************************/
(2)标准
在模块、类、属性、方法前一行添加注释,以便调用的时候提示用户
如果模块只进行部分少量代码的修改时,则每次修改须添加以下注释:
///修改人:
///修改日期:< YYYY-MM-DD >
///备份:
/* 原代码内容*/
将原代码内容注释掉,然后添加新代码使用以下注释:
///添加人:
///添加日期: <YYYY-MM-DD>
代码内容
///结束:
对于重构的类文件,需要对原来的类文件做备份,然后放在同级目录下,在原有文件名后面添加后缀"_BAK",以便日后版本升级时整理源码。
(3)代码间
- 单行注释://
- 多行注释:
/*多行注释1
多行注释2*/
代码中遇到语句块时必须添加注释(if,for,foreach,……),添加的注释必须能够说明此语句块的作用和实现手段(所用算法、循环条件、不同分支的意义等等)。
三、命名总体规则
- 标识事物,业务挂钩
- 英文单词,而非拼音。
- 两个或三个单词组成,不应多于4个,控制在3至30个字母以内。
- 多个单词用大写第一个字母(其它字母小写)来分隔。例如:IsSuperUser。
注:在具体任务开发中,如果有特定的命名约定,则在相应的软件开发计划中予以明确定义及上报质量管理部审计组。
四、命名规范
- 概述
Pascal命名法:所有单词的首字母都大写,其他字母小写(MyBook)
Camel命名法:除首字母外,其他单词的首字母大写,其他字母小写(myBookList)
- 在类属性的名称中包含类名多余,如 Book.BookTitle;应使用 Book.Title。
- 在变量名中使用互补对,如 min/max、begin/end 和 open/close。
- 布尔变量名应该包含 Is,这意味着 Yes/No 或 True/False 值,如 fileIsFound。
- 即使对于可能仅出现在几个代码行中的生存期很短的变量,仍然使用有意义的名称。仅对于短循环索引使用单字母变量名,如 i 或 j。
- 文件名要和类名相同,一般情况下一个类一个文件,文件名遵从Pascal命名法,无特殊情况,扩展名小写,使用统一而又通用的文件扩展名: C# 类 .cs。
2、缩写
为了避免混淆和保证跨语言交互操作,请遵循有关区缩写的使用的下列规则:
- 不要将缩写或缩略形式用作标识符名称的组成部分。例如,使用 GetWindow,而不要使用 GetWin。
- 不要用计算机领域中未被普遍接受的缩写。
- 用众所周知的缩写替换冗长的词组名称。例如,用 UI 作为 User Interface 缩写,用 OLAP 作为 On-line Analytical Processing 的缩写。
- 对于超过两个字符长度的缩写请使用 Pascal 大小写或 Camel 大小写。但是,应当大写仅有两个字符的缩写,如,System.IO,而不是 System.Io。
- 对于某些名字中单词都比较长的情况,可以自行写一个缩写名字(名字中的关键字不能缩写),将所有的缩写做一个说明文件,放在同级目录下的开头。
3、命名空间
- 命名命名空间时的一般性规则是使用公司名称,后跟技术名称和可选的功能与设计,如下所示: CompanyName.TechnologyName[.Feature][.Design]
- 命名空间使用Pascal大小写,用逗号分隔开。
- TechnologyName 指的是该项目的英文缩写,或软件名。
- 命名空间和类不能使用同样的名字
4、类
- 使用 Pascal 大小写。
- 使用全称避免缩写,除非缩写已是一种公认的约定,如URL、HTML。对于某个命名空间、文件夹下类名中单词都比较长的情况,可以缩写(名字中的关键字不能缩写,其他单词只取首字母),将所有的缩写做一个说明文件,放在同级目录下的开头。
- 不使用下划线(_)。
- 见名知意。
- 数据访问层:类名后加DAL(Data Access Layer)。注意:在.NET中没有DAO的概念,DAO是在Java中出现的,表示一种数据访问方式。
- 业务逻辑层:类名后加BLL(Business Logic Layer),如果类名特长可以使用缩写,但在文档中要注明。缩写的全称和意义。
- 界面层:asp中针对页面的类,不用添加UI前缀或后缀。
- 实体层:实体类后加Entity做结尾,如果其他方法中,调用实体类作为参数,参数前面加小写en,如果参数过长,使用缩写,但在文档中也要注明。
- 如果系统规模比较大,应该考虑,对类进行分组放到不同的文件夹中,便于维护,把握粒度。
5、接口
以下规则概述接口的命名指南:
- 使用 Pascal 大小写。
- 在原有类名基础上加“I”,如:IUserDao
- 不使用下划线(_)。
- 当类是接口的标准执行时,定义这一对类/接口组合就要使用相似的名称。两个名称的不同之处只是接口名前有一个I前缀。或者在实现类名后加“Impl”后缀。
publicinterfaceIComponent
{
}
publicclassComponent: IComponent
{
}
publicclassComponentImpl: IComponent
{
}
6、枚举 (Enum)
- 对于 Enum 类型和值名称使用 Pascal 大小写。
- 命名不能缩写,枚举内的内容可以缩写。
- 命名禁止加Enum 后缀。
7、参数
- 参数名称使用Camel大小写(别的一般都用Pascal)
- 参数名称可缩写
8、方法
- 以动词开头。
- 使用 Pascal 大小写。
- 禁止缩写,除非名词本身含有缩写。如:AddStudentMgr ()
9、属性 (property)
- 以名词或形容词命名。
- 使用 Pascal 大小写。
- 禁止缩写。
10、委托
- 以名词或形容词命名。
- 使用 Pascal 大小写。
- 禁止缩写。
- 如果与事件(event)关联,则名称命名使用EventHandler后缀,否则其他名称均以Delegate后缀结尾。如
// 普通委托定义
public delegate void SetMethodDelegate(string name);
//委托与事件关联
publicdelegate void MouseEventHandler(objectsender, MouseEventArgs e);
11、事件
- 使用 Pascal 大小写。
- 禁止缩写。
- 名称命名使用 Event后缀。
- 用动词或名词命名,带有时间意义,如:MouseMove事件、Closing 事件、Closed 事件。
- 指定两个名为 sender 和 e 的参数。sender 参数表示引发事件的对象。e为事件类的实例。e参数类型使用适当而特定的事件类。
- 用 EventArgs 后缀命名事件参数类。
示例:
publicdelegate void MouseEventHandler(objectsender, MouseEventArgs e);
public event MouseEventHandlerMouseEvent; // 事件定义
以下示例阐释正确命名的事件参数类。
publicclassMouseEventArgs: EventArgs
{
int x;
int y;
public MouseEventArgs(intx,int y)
{
this.x = x;
this.y = y;
}
public int X
{
get
{
return x;
}
}
public int Y
{
get
{
return y;
}
}
}
12、常量 (const)
- 全部大写,单词间以“_”分隔。
- 禁止缩写。
13、字段
- private、protected使用 Camel大小写。
- 禁止使用public。
14、静态字段
- 使用名词、名词短语或者名词的缩写命名静态字段。
- 使用 Pascal 大小写。
15、集合
- 命名使用复数。
16、范型
- 以一个大写字母(建议优先使用T)表示类的类型,以一个小写字母(如:t)表示类名。
五、编码规则
1、大括号
书写规则:
if (expression) (推荐)
{
}
或:
if (expression) {
}
2、缩进
使用一个“Tab”为每层次缩进(默认4个空格,有的规范也要求2个空格,依要求而定,所有IDE都可以设置)。
3、小括号
- 不要把小括号和关键词(if 、while等)紧贴在一起,要用空格隔开它们。如:
if (true)
{
}
- 不要把小括号和函数名紧贴在一起。
- 除非必要,不要在Return返回语句中使用小括号。因为关键字不是函数,如果小括号紧贴着函数名和关键字,二者很容易被看成是一体的。
4、单语句
除非这些语句有很密切的联系,否则每行只写一个语句。
5、模块化
某一功能,如果重复实现一遍以上,即应考虑模块化,将它写成通用函数。并向小组成员发布。同时要尽可能利用其它人的现成模块。
6、函数复杂度
单个函数的功能不能过于复杂,不能超过以下限定:
- 单一功能子函数代码不得超过50行、形参个数不得超过7个、程序嵌套深度不得超过7层。
- 圈复杂度必须在15以内,对程序的修改或扩展不得增加其原有圈复杂度
7、编码风格
编码过程中需遵循以下风格习惯:
- 代码未写,文档先行,注释必须按照固定统一范式撰写。
- 关系运算必须常量在左、变量在右。
- 不许使用复杂的运算表达式,必要时添加括号而不依赖于优先级。
- 魔鬼数字需用宏定义替代。
- 局部变量必须初定义、避免不必要的内存操作、内存操作必须考虑异常处理。
8、版本管理
本项目中,每个任务在完成一个稳定的版本后,都应打包并且归档。源码包的版本号由圆点隔开的两个数字组成,第一个数字表示发行号,第二个数字表示该版的修改号。具体用法如下:
- 当源码包初版时,版本号为 V1.00;
- 当源码包被局部修改或bug修正时,发行号不变,修改号第二个数字增1。例如,对初版源码包作了第一次修订,则版本号为 V1.01;33
- 当源码包在原有的基础上增加部分功能,发行号不变,修改号第一个数字增1,例如,对V1.12版的基础上增加部分功能,则新版本号为 V1.20;
- 当源码包有重要修改或局部修订累积较多导致源码包发生全局变化时,发行号增1。例如,在 V1.15 版的基础上作了一次全面修改,则新版本号为 V2.00。
六、数据库
1、数据库名
数据库名采用首字母大写(Pascal),避免系统保留的表名。如:LibraryMaintainSystem
2、表
使用T_表名,表名采用首字母大写。
如:T_Class
如果系统分多个子系统模块,那么将模块的缩写加在T后,用下划线与表名分开。
如:
基础系统:TB_Class (Basic)
评教系统:TA_表名 (Assess)
考试系统:TE_表名 (Exam)
选课系统:TC_表名 (Choose)
关联数据表:TR_表A表B,两个表首字母大写。
一对多关系,多在前,一在后。
一对一和多对多关系,两个表的先后,以字母排序。
如果分模块,那么将模块缩写添加在T后
如:TBR_ClassGrade 表示基础系统,班级和年级的关系表。
3、字段
命名规则只来自于业务,尽量表达出列的含义(采用Camal)。命名一般为名词或形容词。
4、视图
视图名 = V + “_” + 名称
5、主键
主键名 = PK + “_”+ 表名
5、外键
外键名 = FK + “_” + 表名
6、索引
索引名 = IDX + “_” + 表名 + 相关字段/索引含义。
7、关联
关联指数据库表之间的外键关系
关联名 = RL + “_” + 主表名+ 从表名。
8、存储过程
存储过程名 = PROC + “_” + 存储过程含义。
9、触发器
触发器名 = TR + “_”+ 表名 +“_”+ 触发器类型/自定义名称
触发器类型:Insert触发器加"_I",Delete触发器加"_D",Update触发器加"_U",如:
TR_Customer_I,TR_Customer_D,TR_Customer_U。
附:控件命名规范
类 型 | 前 缀 | 示 例 |
Adrotator | adrt | adrtTopAd |
AccessDataSource | ads | adsPubs |
BulletedList | blst | blstCity |
Button | btn | btnSubmit |
Calendar | cal | calMettingDates |
CheckBox | chk | chkBlue |
CheckBoxList | chkl | chklFavColors |
DataList | dlst | dlstTitles |
DetailView | dvw | dvwTitles |
DropDownList | drop | dropCountries |
FileUpLoad | fup | fupImage |
FormView | fvw | fvwFonts |
GridView | gvw | gvwCity |
HiddenField | hfld | hfldName |
HyperLink | hlk | hlkDetails |
Image | img | imgAuntBetty |
ImageButton | ibtn | ibtnSubmit |
ImageMap | imap | imapSite |
Label | lbl | lblResults |
LinkButton | lbtn | lbtnSubmit |
ListBox | lst | lstCountries |
Literal | ltl | ltlTitle |
Localize | loc | locChina |
MultiView | mvw | mvwForm1 |
ObjectDataSource | ods | odsMenus |
Panel | pnl | pnlForm2 |
PlaceHolder | plh | plhFormContents |
RadioButton | rad | radFemale |
RadioButtonList | radl | radlGender |
Repeater | rpt | rptQueryResults |
ReportViewer | rvw | rvwRecord |
SiteMapDataSource | smds | smdsSite |
SqlDataSource | sds | sdsBooks |
SubStitution | subs | subsTime |
Table | tbl | tblCountryCodes |
TextBox | txt | txtFirstName |
View | vw | vwCity |
Wizard | wiz | wizRegister |
Xml | xml | xmlBooks |
XmlDataSource | xds | xdsTitles |