C#语言编码规范.doc

C#语言编码规范文档编号：SMART-DEV版本号：V1.0C#语言编码规范编写：Bob 日期：2010年12月18日校对：日期：年月日审核：日期：年月日批准：日期：年月日修订记录类别：A 增加 M 修改 D 删除日期版本号类别描述作者2010-12-A初稿Bob目 录1介绍41.1为什么要有编码规范42文件名52.1文件后缀52.2常用文件名52.3类模块级变量定义52.4普通局部变量定义62.5常用的缩写72.6ENUM枚举72.7常量定义82.8其他需要注意的几点82.9类、接口、事件等命名规范82.9.1类命名规范82.9.2接口命名规范92.9.3事件命名规范93注释和缩进排版规则104、项目文件组织及命名规范154.1文件夹的组织154.2文件的组织151 介绍1.1 为什么要有编码规范编码规范对于程序员而言尤为重要，有以下几个原因：1、一个软件的生命周期中，80%的花费在于维护；2、几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护；3、编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码；4、如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品。为了执行规范，每个软件开发人员必须一致遵守编码规范。每个人。2 文件名这部分列出了常用的文件名及其后缀。2.1 文件后缀C#程序使用下列文件后缀：文件类别文件后缀Windows应用程序 C#源文件.CSC#语言开发的ASP.NET程序代码文件的扩展名.ASPX.CSC#语言编译后生成的组件扩展名.DLL2.2 常用文件名常用的文件名包括：文件名用途.XML编译时生成XML的代码注释的文件2.3 类模块级变量定义如果类的私有对象跟属性对应，则私有变量以下划线（“_”）开头。在实体类编写中，如果私有变量同实体对应的数据库表的字段存在一定的对应关系，则变量的名称应该尽量跟数据库中的字段名称保持一致，比如public class DocLibprivate string _docNo;private string _docName;private double _docVersion;private string _docCreateDate;private string _docLastSavedDate;对应的属性定义，只需去掉前面的“_”符号，其他保持一致，比如：public string docNogetreturn _docNo;set_docNo=value;public string docNamegetreturn _docName;set_docName=value;public double docVersiongetreturn _docVersion;set_docVersion=value;如果属性实现比较简单，则按照上面的例子，每个属性的Get和Set方法均在一行内完成。否则，就要按照严格的缩进规则编写，比如下列属性：public PageSize Sizegetreturn _Size;set_Size=value;if(_Size=PageSize.A4)if(_Direction=PageDirection.Vertical)_Width=794;_Height=1123;else_Width=1123;_Height=794;同属性无关的类或模块级私有变量按照普通局部变量规则定义。2.4 普通局部变量定义普通局部变量定义由变量类型简写加变量关键字组成，变量关键字组合的每个单词的首个字母必须大写，比如：private string strUserName;private double dblPriceprivate int intUserAge变量关键字要求能够表示变量的实际意义。下列情况允许使用一些没有实际意义的临时局部变量：1）用于循环体的累加器，比如for(int i=0;i100;i+).2）位于某个函数或模块的内部，并且作用范围在10行以内的，可以临时使用一些不具有实际意思的临时变量，比如：if(area.Type=EditAreaType.ListInput)XmlElement ndListItems=xmlDoc.CreateElement(ListItems);for(int k=0;karea.ListItems.Length;k+)XmlElement ndItem=xmlDoc.CreateElement(Item);ndItem.SetAttribute(Text,area.ListItemsk.Text);ndListItems.AppendChild(ndItem);ndEditArea.AppendChild(ndListItems);代码中ndListItems不具有意义，由于其作用范围很短，允许这样的写法。2.5 常用的缩写常用的数据类型数据类型缩写备注stringstrstrNameDoubledbldblAgeBoolbbCheckedintintintCountDateTimedtdtCreateDateObjectObjobjLockShortShrshrStatusSingleSngsngMaximnmDecimalDecdecAverageLongLnglngBillIncomeCharChrchrDelimiterByteBytbytPixelValueExceptionexexErrorStreamReadersrsrReader2.6 ENUM枚举Enum枚举时，所有单词的首字母必须大写。每个枚举项目必须能够明确表达项目表示的意义，比如如下的代码：public enum EditAreaTypeTextInput=1,DateInput,ListInput,CheckInput一般情况下，要求将第一个元素的值表示为1，而不采用默认的0值2.7 常量定义常量名也应当有一定的意义，格式为 NOUN 或 NOUN_VERB。常量名均为大写，字之间用下划线分隔。例：private const bool WEB_ENABLEPAGECACHE_DEFAULT = true;private const intWEB_PAGECACHEEXPIRESINSECONDS_DEFAULT= 3600;private const bool WEB_ENABLESSL_DEFAULT = false;2.8 其他需要注意的几点1） trycatch中，Exception变量一般使用单字符变量“e”开头，除非特殊需要，否则按此惯例2.9 类、接口、事件等命名规范2.9.1 类命名规范类名应该能够标识事物的特性。名字尽量不使用缩写，除非它是众所周知的，可以有两个或三个单词组成，但通常不应多于三个。在名字中，所有单词第一个字母大写。并且不允许使用下划线，比如：public class CustomerBusiness.public class DocLib.public class FeeBill.类的属性必须参照上一节表述的规范进行编写。类的方法名称要求能够明确表述方法的含义，比如GetUserACL方法表示获取用户的ACL数据（ACL一般表示访问控制列表，即用户权限）。大多数情况下，类的方法必须以Get或者Set开头，分别表示获取数据和操作对象。2.9.2 接口命名规范和类命名规范相同，唯一区别是 接口在名字前加上“I”前缀，例：interface IDBCommand;interface IButton;2.9.3 事件命名规范1)、自定义事件委托的命名方式，以事件名称Handler结尾，Handler能够描述出该类型是用于处理某件事件。比如public delegate void MouseUpHandler(object sender, MouseEventArgs e);用于处理当MouseUp时触发的事件。3 注释和缩进排版规则3.1 文件头注释在代码文件的头部进行注释，标注出创始人、创始时间、修改人、修改时间、代码的主要功能，它们可以使后来维护/修改的人员在遇到问题时，在第一时间知道他应该向谁去寻求帮助，并且知道这个文件经历了多少次迭代、经历了多少个程序员的手。样本：/* 创始人：梁远华 创始时间：2004-6-8* 功能描述：主要用于产品信息的资料录入，* 修改人：刘肖 修改时间：2004-12-9* 修改内容：将修改内容填写在这里* 修改人：刘肖 修改时间：2004-12-9* 修改内容：将修改内容填写在这里*/创始人和修改人之间必须间隔一行，便于阅读。后续的修改人在进行功能修改时，必须在修改内容中明确注释修改前后的功能差异。文件头注释如果太长（超过20行），可以使用#region 文件头注释#endregion进行收缩。3.2 类及其属性、方法的注释1）、属性注释，在类的属性必须以以下格式编写属性注释：/ / 是否自增/ 2）、类的注释：类注释的主要内容为类的主要功能，必要时必须给出调用的范例。比如：/ / 用于工程资料管理软件中的文档资料管理库。/ / 本文档库只用于操作文档，不会显示文档。呈现文档必须使用其他相关控件。public class DocLib3）方法注释：每个方法前都必须进行注释，对于私有方法，可能简单注释其功能，对于公共方法，必须详细注释功能、参数以及返回值等，比如：/ / 构造整个文档的XML字符文本/ / 返回构造完毕的文本串public string GetDocData()3.3 代码间注释一般不建议在代码间进行注释，影响代码的可读性和连续性，不过对于下列进行，比如进行代码间注释：1）涉及比较复杂的算法定义或比较复杂的流程构造等。对于此类的算法或流程注释，一般放在模块的开头，或者相应算法的相应位置进行注释。2）模板代码比较长（超过20行的），其中涉及到多个对象操作时，必须在合适的地方加住必要的注释，比如：XmlDocument xmlDoc=new XmlDocument();xmlDoc.LoadXml(strXML);/文档合法性检测./读取模板属性_docNo=ndDocRoot.GetAttribute(No);_docName=ndDocRoot.GetAttribute(Name);./读取所有页XmlNodeList ndPages=ndDocRoot.SelectNodes(Pages/Page);3）涉及到比较严重的，或者非常不明显的BUG修改时，必须在相应的模块位置进行注释，注释内容包括修改之后功能上改进之处，并要注明修改人、修改时间等。如果修改的功能属于明显的错误，或BUG非常明显，则不需要代码间注释，只需在文件头进行相应位置进行标注即可。所有代码间的注释均单独起行，不允许在一行代码的结尾进行注释。注释的文本同样比如符合文档排版的相应规则，进行相应的缩进和换行，保证代码的可读性。代码间注释分为单行注释和多行注释，单行注释比如：/读取所有页XmlNodeList ndPages=ndDocRoot.SelectNodes(Pages/Page);多行注释比如：/* 多行注释内容* 多行注释内容* 多行注释内容*/3.4 缩进规则对于属性定义，如果属性的Get和Set定义都只有一个语句构成，并且实现比较简单，则要求在一行内完成，不要进行缩进。比如下列的属性定义：private string _docNo;private string _docName;/ / 文档编号/ public string docNogetreturn _docNo;set_docNo=value;/ / 文档名称/ public string docNamegetreturn _docName;set_docName=value;否则，如果属性实现比较复杂，则要求按照严格的缩进规则，比如：public int USER_IDgetreturn Convert.ToInt32(this._ClumsValues0);Setthis._ClumsValues0 = value;this._Type0 = Convert.ToByte(this._Type0|0x02);除了属性之外，其他语句一般的缩进都是按照VS.Net开发环境提供的默认缩进规则，即缩进4个字符（一个TAB字符位）。3.5 排版规则1）符合指定的缩进规则和注释规则2）尽量减少代码间的注释3）对于批量的属性赋值，必须进行对齐便于阅读，比如：XmlElement ndEditArea=(XmlElement)ndEditAreasj;area.Index = Convert.ToInt32(ndEditArea.GetAttribute(Index);area.Order = Convert.ToInt32(ndEditArea.GetAttribute(Order);area.Page = Convert.ToInt32(ndEditArea.GetAttribute(Page);area.Width = Convert.ToInt32(ndEditArea.GetAttribute(Width);area.Height = Convert.ToInt32(ndEditArea.GetAttribute(Height);area.Left = Convert.ToInt32(ndEditArea.GetAttribute(Left);area.Top = Convert.ToInt32(ndEditArea.GetAttribute(Top);area.MaxLength = Convert.ToInt32(ndEditArea.GetAttribute(MaxLength);area.EnableImageEmbed= Convert.ToBoolean(ndEditArea.GetAttribute(EnableImageEmbed);area.Key = ndEditArea.GetAttribute(Key);area.Tag = ndEditArea.GetAttribute(Tag);area.Default = ndEditArea.GetAttribute(Default);area.HelpText = ndEditArea.GetAttribute(HelpText);area.FontName = ndEditArea.GetAttribute(FontName);4）一行不易太长，符合一般显示1024768象素的阅读需要。每一行不宜超过100列，超过的部分必须进行合理的断行。3.6 关于#region和#endregion的使用当某区域文本块过长，一般可以使用#region和#endregion将代码进行折叠，并加以注释，便于代码的阅读，不至于使代码过多而导致很乱。符合下列情形的，必须使用REGION命令进行代码折叠：1） 注释超过20行内容，必须对注释部分进行折叠标注2） 代码文件总行数超过200行的，并且包含多个类时，必须对每个类进行折叠标注3） 单个模块比较长时，也可以进行折叠折叠时，比如添加必要的备注信息，比如#region GetUserACL获取用户控制列表#endregion一般情况下，某个代码文件要么全部折叠，要么全部不折叠。如果代码文件过长（数千行），必须实现全折叠，将所有代码进行分块，比如：using SSMARTem;namespace BYSoft.PM.Base#region DocLib文档操作库DocLib库说明及示例public class DocLib属性定义构造函数BindData和GetData函数#endregionPage 页面操作库EditArea 编辑区域操作库4 、项目文件组织及命名规范4.1 文件夹的组织每个项目均使用独立的文件夹，项目文件夹使用英文全称或者简写进行表示，比如OA、CRM、CIS等。对于分层的项目开发，一般在项目文件夹里面建立若干个子文件夹表示相应的层，比如CRMBase表示CRM项目的基础逻辑库，CRMDataAccess表示数据访问层的库，CRMWeb表示Web应用程序，CRMSetup表示安装程序制作等。项目的SLN文件直接放置在项目文件夹下面。4.2 文件的组织每个逻辑层上的文件可以按业务的具体功能来划分。项目命名控件规范1） 所有类库均以SMART开头2） 对于所有项目通用类库，以SMART.Base开头，比如：SMART.Base.SecuritySMART.Base.DataAccessSMART.Base.CommonSMART.Base.WebControlsSMART.Base.WinControls3） 与具体项目有关的，按照SMART加项目关键字缩写组成，项目关键字一般由24个大写字母组成，由公司统一定义，比如PM代表ProjectManager，为工程管理软件项目的缩写，对于每个项目的子类，使用Base表示项目的通用类库，App表示Window应用程序，Web表示网络应用程序，WinControls表示为Windows开发的控件库，WebControls表示为Web应用开发的控件库，比如：SMART.PM.Base.DocLibSMART.CRM.AppSMART.OA.Web.MailSMART.OA.Base.UserASP.NET页面命名规范所有与列表显示有关的Page用：名词+List，如显示相片列表photoList.aspx所有显示详细内容的Page用：名词+ Detailed，如显示某一个新闻内容newsDetailed.aspx显示个人信息内容或用户私有的面板：My+名词.MyProfile.aspx,MyPanel.aspx,MyPortal.aspx,MyVideo.aspx,MyPhoto.aspx,MyAlbum.aspx,MyFirends.aspx,MyMessage.aspx,MyGuestBook.aspx搜索的Page用：名词+Search.aspx用户注册Page：UserRegister.aspx控件命名规范控件类型前缀备注ButtonbtnTextBoxtxtLabellblLinkButtonlikBtnImageButtonimgBtnHyperLinkhyplikDropDownListdrpListBoxlstBoxCheckBoxchkRadioButtonrdoRadioButtonListradlImageimgImageMap