国土软件开发部代码规范(V1.0).doc

国土软件开发部代码规范（V1.0）| 2010年07月07日国土软件开发部代码规范(V1.0)目 录1.概述32.名词解释33.命名33.1.文件(file)33.2.命名空间(namespace)43.3.接口(interface)43.4.类(class)/结构体(struct)/枚举(enum)/委托(delegate)43.5.枚举值(enum item)53.6.属性(Property)53.7.函数(function)/方法(Method)/事件(event)53.8.变量(variance)63.9.常量(const)/标识符(define)83.10.数据库表(table)/视图(view)/存贮过程(procedure)83.11.数据库表字段(Field)94.代码布局94.1.空格分隔104.2.缩进124.3.换行134.4.区段155.错误处理166.注释176.1.文档注释176.2.文件注释186.3.代码注释18SOUTH | 南方数码191. 概述在产品或项目系统的开发过程中，需要多个合作才能完成，这就存在着相互沟通与合作的情况。在现实中，人与人的沟通要有统一的语言，统一的语法，统一的语汇，同样要在代码上实现很好的沟通，也要有统一的语言，统一的语法和统一的书写规范。因为开发语言的选择同时就固定了语法，因此本文档的主要内容将是定义代码的书写规范，解决开发过程中由于代码风格不一致导至阅读和维护的困难。阅读对象是全体开发人员及系统维护人员。2. 名词解释匈牙利命名法：名字可以使用多个单词组合，每个单词第一个字母大写，其余小写，如果是专有名简写，则全部大写。如：Connection，GetMyInfo，GIS。类成员：用于描述一类事物特性的集合，分为属性和行为。其称谓在不同语言叫法不一样： C+对属性称成员变量，对行为称成员函数； C#对属性进行了扩展，用于描述类或成员本身的属性称特性（Attribute，也是元数据），用于类所描述事物的属性称字段（Field），为了控制字段合法性但又象字段一样使用的封装称属性（Property）； C#对行为也进行了扩展，类内部所具有的行为称方法（Method），用于通知外部的行为称事件（Event，但.NET认为事件变量是字段，因此可以通过遍历字段得到事件变量）。3. 命名3.1. 文件(file)保持与文件内定义的类名一致，如果文件内包含多个类时，命名应概括出此文件的主要功能或目的，并以匈牙利法命名。如：FormLogin.csCommUtility.csPrintHelper.cs3.2. 命名空间(namespace)按“公司名.项目名.功能名.子功能名”格式命名，各级名按匈牙利法命名。其中，公司名固定为SouthGIS，子功能名视需要添加。如：SouthGIS.CMS.SysSettingSouthGIS.CMS.Common.PrintHelper3.3. 接口(interface)接口主体名按匈牙利法命名，并加大写字母I前缀。如：interface IDbCommand3.4. 类(class)/结构体(struct)/枚举(enum)/委托(delegate)按匈牙利法命名。如：class Connectionstruct UserInfoenum CommandType常用类型的命名约定：窗体/页面/对话框FormXXXclass FormLogin界面控件CtrlXXXclass CtrlConnPanel用于事件处理的委托XXXEventHandlerdelegate void CancelEventHandler(object sender,CancelEventArgs e)用于回调的委托XXXCallbackdelegate int DownloadedCallback功能性静态类XXXHelperstatic class PrintHelper3.5. 枚举值(enum item)1.使用枚举值需要枚举名时（比如C#语言），按匈牙利法命名。如：Text = 02.使用枚举值不需要枚举名时（比如C+语言），主体名按匈牙利法命名，并添加枚举名前缀并以下划线分隔。如：CT_Text = 0注：前缀规则如下：如果枚举名只是一个单词时，取前3个字符大写。如：enum AdjustmentADJ_Left = 0,ADJ_Right = 1如果枚举名由两个或以上单词组成时，取每个单词首字母大写。如：enum CommandTypeCT_Text = 0,CT_Table = 1,CT_Procedure = 23.6. 属性(Property)按匈牙利法命名，主体名使用名词，也可包含代词等其它词修饰，主要以能概括出属性的功能为目的。如：string UserNameget;set;3.7. 函数(function)/方法(Method)/事件(event)按匈牙利法命名，主体名使用动词，且是第一个单词，后面可以接名词或其它词，主要以能概括出函数功能为目的。如：string GetUserName(int _iUid);event ClickEventHandler Click;3.8. 变量(variance)变量主体名使用匈牙利法命名，使用一个数据类型前缀，再针对作用范围使用一个范围前缀。作用范围前缀的作用，是防止变量定义多了时，很可能名字相似而导致的错误输入；同时，在IDE中，有前缀可以达到帮助记忆的功能，比如定了成员变量，在使用时直接输入前缀，IDE会自动将所有成员变量列出。数据类型前缀的作用，在IDE开发环境中，可以达到帮助记忆的功能；另外，能让阅读代码的人员快速知道变量类型，在一定程度上可以帮助查找错误的功能。变量主体名使用名词，也可包含代词等其它词修饰，主要以能概括出变量的作用为目的。变量主体名需要有明确的含意，不允许出现单字符或只表示类型的变量，对for/foreach的循环变量名尽量简单但也应有明确的含意（如：iPos，iInx等），对一些数学符号如果在使用范围内不会引起混乱时，可以使用单字符（如：iX,iY）。变量主体名长度限制在20字符内，名词的选择以简单常用为主，如果使用单词太长，可截取单词的前4至6个字符（如：sConnString）作用范围前缀：作用范围前缀说明举例全局变量注1g_（小写字母g加下划线）string g_sConnString类静态变量s_（小写字母s加下划线）static string s_sConnString类成员变量m_（小写字母m加下划线）private static m_sConnString界面控件注2（无）TextBox txtUserName函数形参（无）void Func(string sConnString)局部变量（无）string sConnString注1：在.NET开发平台下，没有全局变量。注2：对于界面控件成员，由于IDE会参与管理，因此不需要加m_前缀。变量类型前缀：变量类型前缀说明举例boolbbool bValuebytebybyte byValuesbytebssbyte bsValuecharcchar cValueshort/int/long(Int16/Int32/Int64)n/i/lshort nValueInt64 lValueushort/uint/ulongun/ui/uluint uiValueWORD/DWORDw/dwWORD wBitfloatffloat fValuedouble/decimalddouble dValuedatetimedtdatetime dtValueGuidgGuid gValuestringstrstring strValueobjectobjobject objValue一个单词的结构、接口、类、枚举注3名字前3个字符Record recName两个单词的结构、接口、类、枚举第一个单词首字符加后一个单词的两个字符ArrayList aliName三个或以上单词的结构、接口、类、枚举前三个单词的首字母KeyValuePair kvpName用定义的数组-a（在类型前缀后加a）string straNameRecord recaName变量指针注1p-（在类型前缀前加p）string* pstrNameRecord* precName函数指针注2pfnCompFunc* pfnMsgHandle资源句柄hHBITMAP hBackground注1：在.NET开发平台，一般不建议使用指针；注2：在.NET开发平台，没有函数指针，而是使用代理类型；注3：以下是常用类型变量的前缀约定。未在此表中列出的，按规则命名。Typet类型类Listlst列表集合类Dictionarydic字典集合类Tabletbl所有指数据库表的类型Viewvw所有指视图的类型Connectioncon所有数据库连接的类Commandcmd所有执行数据库查询的类DataAdapterda所有数据库查询适配器的类DataReaderdre所有读数据库记录的类DataSetdsDataTabledtbDataRowdrwDataColumndc窗体类frm不再区分对话框TextBoxtxtButtonbtnLabellblLinkLabellnkCheckBoxchkRadioButtonrdoPanelpnlListBoxlbxComboBoxcmbListViewlvwTreeViewtreTabControltabTimertmImageimgDataGriddg3.9. 常量(const)/标识符(define)名称全部大写，如果有多个单词，单词间以下划线(_)分隔。如：const string PATH_SEPARATOR = ;#define DEBUGERROR_END:3.10. 数据库表(table)/视图(view)/存贮过程(procedure)名称全部大写，单词间以下划线(_)分隔。表名必须要有一个用于分类的单词为前缀，所有相同用途或用于完成相同功能的表要有相同的前缀。表主体名要么用一个或多个英文单词，要么用汉语拼音首字母，不允许使用英文单词的首字母命名。分类前缀将由项目分类名和功能分类名组成，两者间不需要加下划线，命名规则为：如果表针对所有项目适用，则不用加项目分类名，如果仅当前项目适用，则截取项目名前四个字符（不够四个字符则取项目名全部）做为项目分类名；在项目内按表的作用规划功能分类名；如：create table CMSSYS_RIGHTcreate table CMSYW_DJDCBcreate table WF_CONTROLcreate table WF_STEP3.11. 数据库表字段(Field)名称全部大写，如果有多个单词，单词间以下划线(_)分隔。字段主体名要么用一个或多个英文单词，要么用汉语拼音首字母，不允许取英文单词首字母的方法命名，也不允许在同一个表中（包括表主体名与字段名）混用英文单词和汉语拼音首字母的命名方法（但表记录标识字段可以除外）。如：create table CMSORG_USER_INFO(RID int identity,NAME varchar(60),USE_RIGHT int)create table CMSORG_DJDCB(RID int identity,ZDH varchar(20),SYQR varchar(60),)4. 代码布局按VS2010全局设置布局标准4.1. 空格分隔l 方法申明时，方法名与左小括号间、小括号与参数列表间不要空格l 方法调用时，方法名与左小括号间、小括号与参数列表间不要空格l 流程控制段中在关键字后插入一个空格l 流程控制段中小括号与表达式间不要空格l 左右小括号与表达式间不要空格l 类型转换的左右小括号与类型间、转换与表达式间不要空格l 申明代码只用一个空格分隔上下申明代码间不要对齐l 中括号前、中括号与表达式间不要空格l 类型和基类（或接口）间的冒号前后插入一个空格l 在逗号后插入一个空格l 在逗号前不要空格l 在点号前后不要空格l 在“for”语句的分号后插入一个空格l 在“for”语句的分号前不要空格l 在运算符号前后插入一个空格4.2. 缩进l 代码块内容缩进l 分隔代码块的左右大括号不缩进l switch的case块内容缩进l switch的case标签缩进l 标签符比所在代码块少缩进一级4.3. 换行l 左大括号在新行（类型定义、方法定义、匿名方法、控制块、匿名类型、对象初始化、lambda表达式）l 控制块关键字在新行（else、else if、catch、finally）l 对象初始化分行l 匿名类型成员定义分行l Linq查询表达式按子句分行（如果较短时，可以写在一行）l 如果代码块较简单，可以在一行输入l 变量申明分行但对相同类型的变量，且作用相关时，可以申明在一行内4.4. 区段在C#开发语言中，可以用#region指令包含代码块。主要作用是将一些结合紧密的代码包含起来，在布局上更清楚，更容易阅读。因此，在一些复杂函数或类定义中，一定要将相关性比较大的函数或代码用#region包含，并写上区段说明：#region 初始化拓扑规则m_dicTopoRules = new Dictionary(26);m_dicTopoRules.Add(点必须被面边界覆盖,new TopoRuleInfo(esriRuleType.esriTRTPointCoveredByAreaBoundary,0x0103);m_dicTopoRules.Add(点必须被线终点覆盖,new TopoRuleInfo(esriRuleType.esriTRTPointCoveredByLineEndpoint,0x0102);m_dicTopoRules.Add(点必须被线覆盖,new TopoRuleInfo(esriRuleType.esriTRTPointCoveredByLine,0x0102);m_dicTopoRules.Add(点必须完全位于面之内,new TopoRuleInfo(esriRuleType.esriTRTPointProperlyInsideArea,0x0103);#endregion#region 格式化函数public string FormatInt()public string FormatDouble()public string FormatDate()public string FormatString()#endregion5. 错误处理功能性处理函数内部不要捕获异常，界面交互函数一定要捕获异常并对异常进行处理。class FrmLoginvoid butLogin_Click(.)tryint iRight=Login(texUser.Text,texPassword.Text);catch(Exception ex)/异常处理，如显示给用户，记录到日志文件MessageBox.Show(ex.Message);finally/最后的清理工作，如果没有，可以不用这块。int Login(string sUser,string sPwd)/此函数内不应捕获异常功能性处理函数内部如果要处理异常时可以捕获，但在处理完后，视情况做后续处理：如果可以继续执行的，应正常返回给调用者继续执行；如果不能继续执行的，应抛出异常。不能直接将捕获的异常错误消息显示给用户（这应该由界面交互函数来做）。int Login(string sUser,string sPwd)trycatch(ConnException ex)/处理预期的已知异常/处理完后，可以继续执行时，不用抛出异常，应正常返回catch/处理其它所有异常/处理完后，如果不能继续执行时，可以继续抛出或重新抛出异常。throw;/继续抛出捕获的异常/throw new Exception(登录失败);/重新抛出一个新异常finally/最后的清理工作，如果没有，可以不用这块。另一种写法：int Login(string sUser,string sPwd)tryfinally/仅仅做最后的清理工作时，不要catch块。此时会继续向上层调用者抛出6.