代码规范（CS）

代码规范（CS）

总则

1.1.      目的

为了对程序员的开发进行适当的规范化，特制定本规范。其根本目的，是为了保证程序具有良好的、一致的结构，以期提高程序的可读性及可维护性，方便程序的测试、维护、升级等工作，同时，也培养程序员书写代码的规范性。

1.2.      原则

名称反映含义,形式反映结构。

1.3.      申明

本规范适用于采用MS .NET作开发工具的公司所有项目，程序员应严格按照本规范编写代码，如项目有确实需要的特殊要求，也必须经项目经理审核后，把该特殊要求形成文档当作本文档的随附文件一起保存。

代码规范

2.1.      项目规范

2.1.1.       每一个项目的代码、文档按模块、功能必须在该项目VSS上有条理的归类存放，每个项目VSS上均必须包含以下子目录：

²        Code：源代码目录

²        Sql：数据库脚本目录

²        Demodata：演示数据目录

²        Userdata：用户数据目录

²        Help：帮助文档目录

²        Install：安装文件目录

²        Document：文档目录

²        Picture：图片目录

²        templates：模板目录

            

子目录下也必须依照详细的用途分类建立子目录。

 

2.1.2.       每个项目的主目录下均必须有一个项目说明文件，说明该项目的一些概要性提示和相关规范。

2.1.3.       在项目目录下的每层子目录中必须有一个目录说明文件，说明该层目录及其子目录的分类方法和含义。任何时候，新增一个目录时，均必须在同层目录下的目录说明文件中添加所新增目录的分类含义，同时创建该目录下的目录说明文件。

2.1.4.       工程文件代码规范：

²        任何一个工程文件（包括动态链接库工程文件）的第一部分必须用注释的形式说明项目名称、公司版权、工程描述、版本说明、创建日期、作者以及后续更新人员。

²        除主模块、公共函数模块和公共数据模块外，所有该项目下的单元不可由项目自动创建（CREATE），在加入新单元后，必须在工程文件中删除自动CREATE的语句。

²        工程文件的其余代码遵行本文档约定的单元规范及其它代码规范。

2.2.      源代码文件总体规范

2.2.1.       每个源代码文件的第一部分必须用注释的形式说明项目名称、公司版权。

2.2.2.       在Using和NameSpace之间，以注释的形式说明项目名称、模块名称、模块描述、模块版本、创建日期、作者、更新人以及TODO列表。

2.2.3.       每个类之前或者方法、属性、事件之前要有相应的注释。

2.2.4.       对于有参数的类，要对参数的含义进行说明。

2.2.5.       总体风格

²        缩进规则：每级间保持一个“Tab”键的距离。

²        边距页宽：每一行的程序不要过长。最好不要超过80个字符。如果超过，要进行换行。

²        注释规则：如果只注释一行，使用“//”作为注释符。多行注释，使用“/*……*/”作为注释符。

²        空行使用：需使用空行的地方有：版权块、类之间、方法过程函数之间、方法内部算法分段。空行只能用一行，多余的空行必须删除。

示例：

/********************************************************

 

                     项目名称                            

 

            版权所有 (C) 2000,2001 公司名称

 

********************************************************/

 

using System;

using System.Data;

/********************************************************

项目名称:

模块名称:

描述:

版本:

日期:

作者:

更新:

TODO:

********************************************************/

       namespace InfoComm.DVAP

{

/// <summary>

///   作者:

///   日期:

        ///     描述:

        /// </summary>

public class Utilities

{

            /// <summary>

  /// 作者:

/// 日期:

            ///     描述:

            /// </summary>

            /// <returns></returns>

            public static string ConnectionString()

            {

                return "ConnectionString";

     }

}

}

2.3.       源代码内部规范

2.3.1.       常量定义

²        所有常量的第一个前缀必须为C，常量必须分主题归类定义，如有多个主题，每一个主题必须加一个主题前缀。前缀与前缀之间、前缀与名称之间用_分割。

²        每个常量的定义单独一行，在同一行上，必须用“//”加注释说明该常量的含义。

²        按主题归类的常量，在每个主题开始的第一行必须用“//”注释主题含义。

示例：

Const

 

  { 主题1 }

C_主题前缀1_---    = ----；  // 含义

C_主题前缀1_---    = ----；  // 含义

C_主题前缀1_---    = ----；  // 含义

C_主题前缀1_---    = ----；  // 含义

  { 主题2 }

C_主题前缀2_---    = ----；  // 含义

C_主题前缀2_---    = ----；  // 含义

C_主题前缀2_---    = ----；  // 含义

C_主题前缀2_---    = ----；  // 含义

 

2.3.2.       类型定义

 

2.3.3.       变量定义

²        变量定义时，变量名必须有明确的含义，不能用数字作为名字。

²        变量分为全局变量和局部变量。全局变量需要加“m_”前缀。

²        局部变量的第一个字符必须小写。以后的字符，根据英文的语法进行大小写区分。

²        每个需要注释的变量单独一行，在行末尾用“//”注释其含义。

²        同一类型且含义逻辑上不并列的变量分开定义，同一类型且含义逻辑上并列的变量在一起定义。

²        一般不鼓励使用全局变量。在确实需要使用全局变量的时候，必须把全局变量限制在需要的环境内。

²        全局变量可以在定义时直接初始化为某一个值。

²        变量的命名规则参见本文档后面的命名规则项。

2.3.4.       程序主体

²        事件、过程、函数应按主题分类归集在一起，每个主题开始的第一行用“/*…*/”注释该类主题。约定归类方法如下：同一个控件的事件应归集在一起，被事件调用或与之相关系的函数或过程应紧跟在该事件之后，函数、过程、方法之间如存在调用关系也应归集在一起，除非该函数、过程被多处调用。被多处调用的类内部函数、过程应归集在类的公共过程主题内。可以自定义归类方法，比如按实现功能归类，但如归类方法不同于本约定的，应在所有主题之前用“/*…*/”注释说明归类方法。

²        每一个事件、方法必须在其代码前用“/*…*/”注释说明名称、描述、参数含义、创建时间、作者、更新人、更新时间。在事件、方法内部不同含义的算法或不同主题的代码间空一行，每段算法或主题的开始用“/*…*/”注释算法或主题的目的。关键性的算法行应在行末尾用“//”注释算法目的。事件、方法内部的变量定义时必须遵行2.3.3约定的变量区规范。

²        SQL 语句书写规则：在SQL语句中，所有SQL保留字统一用大写，所有字段名以及数据表名全部用小写，SELECT, FROM, WHERE, ORDER BY 顶格起行，各子句中要求每个字段或每个条件或每个关联单独起行. 并缩进对齐，缩进以两格为准。

注意：CASE...WHEN...THEN...ELSE...END语句的写法不同。

²        代码中用到数据库字段名称的地方，统一用小写。

2.4.      语法约定

2.4.1.       语法杂项

²        运算符前后要有各一个空格。

²        在开始圆括号和后一个字符，以及结束圆括号和上一个字符中不出现空格。

²        保留字和关键字总是小写。

2.4.2.       过程与函数

²        形参的顺序主要考虑寄存器调用规则。

²        最常用的参数应当作为第一个参数，按使用频率依次从左向右排。

²        输入参数应当位于输出参数之前。

²        范围大的参数应当放在范围小的参数之前，如SomeProc(string country,  string state, string city)。

²        IDE自动生成的事件句柄，参数顺序不必依此约定。

²        所有的常量参数应当标以Const标记。

²        除非确实需要在使用前再初始化，否则例程的内部变量应当在例程的入口处立即初始化。

2.4.3.       语句规范

²        if语句：

在if/then/else语句中，最可能执行的情况应放在then子句中，出现可能较小的情况放在else子句。

²        不要嵌套5层以上的if语句。

²        如果if语句过多，可以考虑使用switch语句。

²        如果if语句中存在多个条件判断，条件应该按从最快的到最慢的计算难度依次从左到右排列整齐。

²        switch…case语句：

switch…case语句中，代表每种情况的常量应该按照数字或字母顺序排列。

每种情况所对应的动作语句应当简短且通常不超过4-5行。如果动作太复杂，应将代码放到一个单独的过程或函数中。

switch…case语句的default子句只用于默认情况或错误检测。

switch…case语句的规范示例：

switch(n)      

            {

          case 1:

                     cost += 25;

                     break;

         case 2:

                     cost += 25;

                     goto case 1;

         case 3:

                      cost += 50;

                     goto case 1;

                default:

                     Console.WriteLine("Invalid selection. Please select 1, 2, or 3.");

                     break;

           }

²        while语句：

while 语句执行一个语句或一个语句块，直到指定的表达式求得 false 值为止。可以用break去终止程序。

所有对while循环进行初始化的代码应当位于while入口前，且不要被无关的语句分隔开。

while语句的规范示例：

int n = 1;

while (n < 6)

 {

         Console.WriteLine("Current value of n is {0}", n);

         n++;

 }

²        for语句：

for 循环重复执行一个语句或一个语句块，直到指定的表达式求得 false 值为止。

如果循环次数是确定的，应当用for语句代替while语句。

for语句的规范示例：

for (int i = 1; i <= 5; i++)

         Console.WriteLine(i);

²        try…catch… finally语句：

需要在发生异常时执行一些自定义的任务，才使用try…catch。

如果要在catch子句中激活默认的异常处理，可以用throw再次触发异常。

Try语句的规范示例：

try

     {

         string s = null;

         x.MyFn(s);

      }

 

      // Most specific:

      catch (ArgumentNullException e)

      {

         Console.WriteLine("{0} First exception caught.", e);

      }

 

      // Least specific:

      catch (Exception e)

      {

         Console.WriteLine("{0} Second exception caught.", e);

      }

2.5.       命名规范

2.5.1.       过程、函数的命名规则

²        例程名以大写字母开始，且应在具有不同词义单词的第一个字母处用大写。

²        例程名应当有意义，并应尽量使用动宾词组。

²        设置输入参数值的例程名应当以Set为其前缀，获取数值的例程名应当以Get为其前缀。

²        例程的形参名称应当表达出它的用途，只要可能，形参名称的第一个字母应小写。

²        IDE自动产生的事件句柄，名称和参数不可作改动。

2.5.2.       变量命名规则

²        变量的名称应当能表达出它的用途。尽量不缩写，并使用名词作为变量名。

²        变量名应该用类型的缩写作为前缀，比如strMasterSql。

²        循环控制变量可以是单个字母如i、j、k，也可以使用具有含义的名称。

²        布尔变量的名称必须能清楚的表示出true和false的意义。

²        工程的全局变量应该以g_作为前缀。类内的全局变量应该以m_作为前缀。

 

2.5.3.       类型、类、对象命名规则

²        定义枚举类型应在名称前加e作为前缀。

²        数组类型名应表达出该数组的用途，类型名必须加字母a为前缀。

²        类的名字必须是能够体现这个类的用途。

²        类的私有数据域(Fields)命名规则和其他的变量一样。

²        类的方法命名和过程、函数的命名一样。

²        类的属性名应该是名词，不是动词。属性的命名规则与类的私有数据域相同。

²        类的事件命名应以ON、BEFORE、AFTER作为前缀。

2.5.4.       文件命名规范

²        工程文件：工程文件应该赋予有意义的名字。可以取工程的全称组成单词的开始字符的大写，或者每个单词的缩写。也可以直接用单个单词命名。

²        窗体文件：窗体文件的名称必须能表达Form的用途，并且具有frm前缀。

²        类文件：文件名必须有意义。

2.5.5.       组件命名规则

²        组件命名标准和类的命名标准相似。不同的是他们有三个字符的标志性前缀。作为前缀的三个字符要用小写。

²        组件实例命名规则：元件类型前缀 + 描述性名称。

²        系统命名空间类前缀如下：

System.Web.UI.WebControls命名空间类

类	缩写	说明
AdCreatedEventArgs	entargs	为 AdRotator 控件的 AdCreated 事件提供数据。无法继承此类。
AdRotator	rot	在 Web 页上显示公布标题。
BaseCompareValidator	bcvld	充当执行类型化比较的验证控件的抽象基类。
BaseDataList	bdlst	用作数据列表控件的抽象基类，如 DataList 和 DataGrid。此类提供所有数据列表控件的公共方法和属性。
BaseValidator	bvld	用作验证控件的抽象基类。
BoundColumn	bcol	绑定到数据源中的字段的 DataGrid 控件的列类型。
Button	btn	在 Web 页上显示普通按钮控件。
ButtonColumn	btncol	DataGrid控件的列类型，该类型包含与列中的每一行对应的用户定义的命令按钮，例如 Add 或 Remove。
Calendar	cal	显示单个月历，该月历使用户可以选择日期并移到下个月或上个月。
CalendarDay	calday	表示 Calendar 控件中的日期。
CheckBox	chk	显示允许用户选择 true 或 false 条件的复选框。
CheckBoxList	chklst	创建多项选择复选框组，该复选框组可以通过将控件绑定到数据源动态创建。
CommandEventArgs	cmdentargs	为 Command 事件提供数据。
CompareValidator	cmpvld	将由用户输入到输入控件的值与输入到其他输入控件的值或常数值进行比较。
CustomValidator	custvld	对输入控件执行用户定义的验证。
DataGrid	grd	数据绑定列表控件，它在表中显示来自数据源的项。DataGrid 控件允许您选择和编辑这些项以及对它们进行排序。
DataGridColumn	grdcol	作为 DataGrid 控件的不同列类型的基类。
DataGridColumnCollection	grdcolcln	DataGridColumn 导出的列对象的集合，这些对象表示 DataGrid 控件中的列。无法继承此类。
DataGridCommandEventArgs	grdcmdentargs	为 DataGrid 控件的下列事件提供数据：CancelCommand、DeleteCommand、EditCommand、ItemCommand 和 UpdateCommand 事件。无法继承此类。
DataGridItem	grditem	表示 DataGrid 控件中的某项（行）。
DataGridItemCollection	grditemcln	表示 DataGrid 控件中的 DataGridItem 对象的集合。
DataGridItemEventArgs	grditementargs	为 DataGrid 控件的 ItemCreated 和 ItemDataBound 事件提供数据。无法继承此类。
DataGridPageChangedEventArgs	grdpgeentargs	为 DataGrid 控件的 PageIndexChanged 事件提供数据。无法继承此类。
DataGridPagerStyle	grdpgesty	指定 DataGrid 控件的页导航的样式。不能继承此类。
DataGridSortCommandEventArgs	grdcmdentargs	为 DataGrid 控件的 SortCommand 事件提供数据。无法继承此类。
DataKeyCollection	dkcln	表示包含数据源中每个记录的键字段的集合。无法继承此类。
DataList	dlst	显示使用模板的项的数据绑定列表控件。
DataListCommandEventArgs	dlstcmdentargs	为 DataList 控件的下列事件提供数据：CancelCommand、DeleteCommand、EditCommand、ItemCommand 和 UpdateCommand 事件。无法继承此类。
DataListItem	dlstitem	表示 DataList 控件中的项。
DataListItemCollection	dlstcln	表示 DataList 控件中 DataListItem 对象的集合。无法继承此类。
DataListItemEventArgs		为 DataList 控件的 ItemCreated 和 ItemDataBound 事件提供数据。无法继承此类。
DayRenderEventArgs	dayentargs	为 Calendar 控件的 DayRender 事件提供数据。无法继承此类。
DropDownList	ddl	表示允许用户从下拉列表中选择一项的控件。
EditCommandColumn	edtcmdcol	DataGrid 控件的一种特殊列类型，包含用于编辑每行中的数据项的 Edit 命令按钮。
FontInfo	fntinfo	封装文本的字体属性。不能继承此类。
FontNamesConverter	fntncvter	将包含字体名称列表的字符串转换为包含个别名称的字符串数组。它还执行反转功能。
FontUnitConverter	fntucvter	将 FontUnit 转换为具有另一种数据类型的对象。它还将具有另一种数据类型的对象转换为 FontUnit。
HyperLink	hlnk	显示到其他 Web 页的链接的控件。
HyperLinkColumn	hlnkcol	DataGrid 控件的列类型，它包含列中每一项的超级链接。
HyperLinkControlBuilder	hlnkbud	与分析器进行交互以生成 HyperLink 控件。
Image	img	在 Web 页上显示图像。
ImageButton	imgbtn	显示图像并对图像上的鼠标单击作出响应的控件。
Label	lbl	表示在 Web 页上显示文本的标签控件。
LabelControlBuilder	lblbud	与分析器进行交互以生成 Label 控件。
LinkButton	lnkbtn	在 Web 页上显示超级链接样式的按钮控件。
LinkButtonControlBuilder	Lnkbtnbud	与分析器进行交互以生成 LinkButton 控件。
ListBox	lst	表示允许单项或多项选择的列表框控件。
ListControl	lstcon	用作定义所有列表类型控件通用的属性、方法和事件的抽象基类。
ListItem	lstitem	表示数据绑定列表控件中的数据项。不能继承此类。
ListItemCollection	lstitemcol	列表控件中的 ListItem 对象的集合。不能继承此类。
ListItemControlBuilder	lstitembud	与分析器进行交互以生成 ListItem 控件。
Literal	lit	在 Web 页上保留显示静态文本的位置。
LiteralControlBuilder	litbud	与分析器进行交互以生成 Literal 控件。
MonthChangedEventArgs	monentargs	为 Calendar 的 VisibleMonthChanged 事件提供数据。无法继承此类。
PagedDataSource	pgeds	封装 DataGrid 控件的属性，这些属性使该控件可以执行分页。无法继承此类。
Panel	pal	表示作为其他控件的容器的控件。
PlaceHolder	plahld	存储 Web 页上动态添加的服务器控件的容器。
PlaceHolderControlBuilder	plahldbud	与分析器进行交互以生成 PlaceHolder 控件。
RadioButton	rbtn	表示单选按钮控件。
RadioButtonList	rbtnlst	表示封装一组单选按钮控件的列表控件。
RangeValidator	rgevld	检查输入控件的值是否在指定的值范围内。
RegularExpressionValidator	rgeexpvld	验证相关输入控件的值是否匹配正则表达式指定的模式。
Repeater	rep	一个数据绑定列表控件，允许通过为列表中显示的每一项重复指定的模板来自定义布局。
RepeaterCommandEventArgs	repcmdentargs	为 Repeater 的 ItemCommand 事件提供数据。无法继承此类。
RepeaterItem	repitem	表示 Repeater 控件中的项。
RepeaterItemCollection	repitemcol	表示 Repeater 控件中的 RepeaterItem 对象的集合。无法继承此类。
RepeaterItemEventArgs	repitementargs	为 Repeater 的 ItemCreated 和 ItemDataBound 事件提供数据。
RepeatInfo	repinfo	封装用于呈现重复项列表的列表控件的信息。无法继承此类。
RequiredFieldValidator	reqfldvld	使关联的输入控件成为一个必选字段。
SelectedDatesCollection	seldtecol	封装 System.DateTime 对象的集合，这些对象表示 Calendar 控件中的选定日期。无法继承此类。
ServerValidateEventArgs	srvvldentargs	为 CustomValidator 控件的 ServerValidate 事件提供数据。无法继承此类。
Style	sty	表示 Web 服务器控件的样式。
Table	tbl	在 Web 页上显示表。
TableCell	tblcel	表示 Table 控件中的单元格。
TableCellCollection	tblcelcln	封装 TableHeaderCell 和 TableCell 对象的集合，这些对象组成了 Table 控件中的一行。无法继承此类。
TableCellControlBuilder	tblcelclnbud	与分析器进行交互以生成 TableCell 控件。
TableHeaderCell	tblhadcel	表示 Table 控件中的标题单元格。
TableItemStyle	tblitemsty	表示呈现为 TableRow 或 TableCell 的控件元素的样式属性。
TableRow	tblrow	表示 Table 控件中的行。
TableRowCollection	tblrowcln	封装 TableRow 对象的集合，这些对象表示 Table 控件中的单行。无法继承此类。
TableStyle	tblsty	表示表控件的样式。此类主要由控件开发人员使用。
TargetConverter	tarcvter	将表示显示从 Web 导航产生的内容的位置（目标）的值转换为字符串。它还将字符串转换为目标值。
TemplateColumn	tepcol	表示 DataGrid 控件的列类型，它使您得以自定义列中的控件布局。
TextBox	txt	为用户输入显示一个文本框控件。
TextBoxControlBuilder	txtbud	与分析器进行交互以生成 TextBox 控件。
UnitConverter	ucvter	将 Unit 转换为另一种数据类型的对象。它还将另一种数据类型的对象转换为 Unit。
ValidatedControlConverter	vldcvter	将 Web 窗体页上可以用验证控件进行验证的控件转换为字符串。
WebColorConverter	webclrcvter	在预定义颜色名称或 RGB 颜色值与 System.Drawing.Color 之间相互转换。
ValidationSummary	vldsum	在 Web 页、消息框或在这两者中内联显示所有验证错误的摘要。
WebControl	webcon	用作定义 System.Web.UI.WebControls 命名空间中的所有控件的公共方法、属性和事件的基类。
Xml	xml	显示 XML 文档，不进行格式化或使用扩展样式表语言转换 (XSLT)。