C#编程规范(研发中心).doc

C#编程规范一、规范目的1：一个软件的生命周期中，80%的花费在于维护；合理的规范可以减少后期开发人员对代码的维护。2：编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码。为了执行规范，每个软件开发人员必须一致遵守编码规范；3：使用统一编码规范的主要原因，是使应用程序的结构和编码风格标准化，以便于阅读和理解这段代码；4：好的编码约定可使源代码严谨、可读性强且意义清楚，与其它语言约定相一致，并且尽可能的直观。二、适用范围研发中心全体.NET开发人员。三、规范内容3.1 命名规范变量，类等命名方式主要采用以下两种：序号名称规范实例1Pascal所有单词第一个字母大写，其他字母小写如：HelloWorld。此方式主要用于类，方法等命名2Camel 除了第一个单词，所有单词第一个字母大写，其他字母小写如：helloWorld。此方式主要用于变量命名。3匈牙利命名法所有命名加前缀如btnXX,txtXX。可用在界面上一些按钮，文本或变量的定义。3.1.1变量命名规范1：变量和方法参数使用Camel 大小写形式如：public class HelloWorld int totalCount = 0; void SayHello(string name) string fullMessage = "Hello " + name; . ：不要使用匈牙利方法来命名变量。即采用“_”或“X_”做为前缀，例如：string m_sName；Object _obj；等。所有变量均采用camel 大小写形式。：不要用“_”或“&”等特殊字符作为第一个字母；：用有意义的，描述性的词语来命名变量。项目中可商量是否统一采用中文拼音的首字母来做为变量或参数的命名。3.1.2属性命名规范：用名词或名词短语命名属性。：用Pascal大写命名属性。3.1.3 方法命名规范：如果方法返回一个成员变量的值，方法名一般为Get+成员变量名，如若返回的值 是bool变量，一般以Is作为前缀。另外，如果必要，考虑用属性来替代方法；：如果方法修改一个成员变量的值，方法名一般为：Set + 成员变量名。同上，考虑 用属性来替代方法。：用动词或动词短语命名方法。：使用Pascal大写方式命名方法。如下所示：void RemoveAll()string GetCharArray()bool IsContain()3.1.4 类命名规范：用名词或名词短语命名类：使用Pascal大写。：不要使用任何类前缀以及不要使用带下划线的字符。：泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：public class List<T>public class MyClass<Tsession>：对同一项目的不同命名空间中的类，命名避免重复，避免引用时的冲突和混淆。 6：自定将异常类使用Exception作为后缀，如MyException。3.1.5接口命名规范：所有接口命名都以I做为开头，以表示这个类型是一个接口。：使用名词或名词短语，或者描述行为的形容词来命名接口。：使用Pascal大写。同时I不算在内。如：IComponent（描述性名词），ICustomAttributeProvider（名词短语），和IPersistable（形容词）：不要在任何地方使用带下划线或其经特殊的字符。3.1.6事件命名规范1：定义为事件的委托，使用EventHandler做为后缀。如public delegate void MouseEventHandler(object sender, MouseEventArgs e);2：考虑使用动词命名事件。3：使用Pascal命名，不要使用任何前缀或后缀。例如，使用 Close，而不要使用 OnClose。4：通常情况下，对于可以在派生类中重写的事件，应在类型上提供一个受保护的方法（称为OnXxx）。如：Public virtual void OnClose() If(Close!=null) Close(); 3.1.7 常量命名规范所有单词大写，多个单词之间用 "_" 隔开。 如public const string PAGE_TITLE = "Welcome"3.1.8 静态字段命名规范1：使用Pascal大小写2：对静态字段名称使用匈牙利语表示法加前缀。一般可采用“_”做为前缀。3：使用名词、名词短语或者名词的缩写命名静态字段。3.1.9项目和程序集命名采用公司简称+项目名+模块名(可选)命名方式。3.2代码注释规范3.2.1代码注释约定所有的方法和函数都应该以描述这段代码功能的简明注释开始（方法是干什么）。 但这种描述不应该包括执行过程细节（它是怎么做的），因为这常常是随时间而变的，而且这种描述会导致不必要的注释维护工作，甚至更糟成为错误的注释。因此只需要简单描述此段代码的基本功能即可另外当参数的功能不明显且当过程希望参数在一个特定的范围内时，也应描述传递给过程的参数。被过程改变的函数返回值和全局变量，特别是通过引用参数的那些，也必须在每个过程的起始处描述它们。3.2.2模块头部注释规范以一个物理文件为单元的都需要有模块头部注释规范，例如：C#中的.cs文件用于每个模块开头的说明，主要包括：序号名称选择描述1文件名称必选此文件的名称2功能描述必选此模块的功能描述与大概流程说明3作者必选当前文档编写者4日期必选当前文档创建日期5参考文档可选该档所对应的分析文档，设计文档。6引用可选开发的系统中引用其它系统的Dll、对象时，要列出其对应的出处，是否与系统有关不清楚的可以不写，以方便后期维护。7修改记录后期开发必选若在后期或二次开中档案的功能改变，则需要有修改人员的名字、修改日期及修改理由。8数据表可选所用到的数据表，视图，存储过程的说明，如关系比较复杂，则应说明哪些是可擦写的，哪些表为只读的。如下例所示实例：/* * 文件名：ICycleEngine.CS * 基本功能：在后台线程中进行间隔循环的引擎接口 * 作者： HCB * 日期： 2013年8月5日 * 修改记录 * 修改日期 * 修改人： * 修改理由：*/namespace ESBasic.Threading.Engines / <summary>/ ICycleEngine 在后台线程中进行间隔循环的引擎接口/ HCB 2013年8月5日 / </summary> public interface IcycleEngine3.2.3类属性注释规范在类的属性必须以以下格式编写属性注释：/ <summary>/属性说明/ </summary>3.2.4方法注释规范1：使用C#提供的机制。即包含XML 文本的特殊注释语法为方法进行注释。在进行注释时，对所有参数以及返回值都要进行简要说明。只要在方法头敲“/”三个斜杠系统自动生成基本如下所示的XML标签格式的注释：/ <summary>/ 说明：<对该方法的说明>/ </summary>/ <param name="<参数名称>"><参数说明></param>/ <returns>/<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义>/ </returns>2：对于公共类的方法，在后期开发或维护当中需要进行修改时，必须对修改人，修改日期，修改理由进行说明。3：所有的方法必须在其定义前增加方法注释。4：方法注释的XML文档中所有标签节点说明如下：标签用法作用<c>c>text</c> text 希望将其指示为代码的文本。为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码<para><para>content</para>content段落文本。用于诸如 <remarks> 或 <returns> 等标记内，使您得以将结构添加到文本中。<param><param name='name'>description</param>name 为方法参数名。将此名称用单引号括起来 (' ')。应当用于方法声明的注释中，以描述方法的一个参数。<paramref> <paramref name="name"/>name 要引用的参数名。将此名称用双引号括起来 (" ")。<paramref> 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件，从而用某种独特的方法格式化该参数。<see><see cref="member"/>cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中。使您得以从文本内指定链接。使用 <seealso> 指示希望在“请参阅”一节中出现的文本。<seealso><seealso cref="member"/>cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中使您得以指定希望在“请参阅”一节中出现的文本。使用 <see> 从文本<example><example>description</example>description 代码示例的说明。使用 <example> 标记可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到 <code> 标记的使用。<code><code>content</code>content 为希望将其标记为代码的文本。 记为您提供了一种将多行指示为代码的方法。使用 <c> 指示应将说明中的文本标记为代码<summary><summary>description</summary>此处description 为对象的摘要。应当用于描述类型成员。使用 <remarks> 以提供有关类型本身的信息。<exception><exception cref="member">description</exception>cref = "member" 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。description 说明。<exception> 标记使您可以指定类能够引发的异常。<include><include file='filename' path='tagpathname="id"' />filename 包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')。 Tagpath：filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')。 name 注释前边的标记中的名称说明符；名称具有一个 id。 id 位于注释之前的标记的 id。将此 id 括在双引号中 (" ")。<include> 标记使您得以引用描述源代码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法，请参阅 XPath 文档。<list> <list type="bullet" | "number" | "table"> <listheader> <term>term</term> <description>description</description> </listheader> <item> <term>term</term> <description>description</description> </item></list>term 定义的项，该项将在 text 中定义。 description 目符号列表或编号列表中的项或者 term 的定义。<listheader> 块用于定义表或定义列表中的标题行。定义表时，只需为标题中的项提供一个项。列表中的每一项用 <item> 块指定。创建定义列表时，既需要指定 term 也需要指定 text。但是，对于表、项目符号列表或编号列表，只需为 text 提供一个项。列表或表所拥有的 <item> 块数可以根据需要而定。<permission><permission cref="member">description</permission>cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。 description 成员的访问的说明。<permission> 标记使您得以将成员的访问记入文档。System.Security.PermissionSet 使您得以指定对成员的访问。<remarks><remarks>description</remarks>description 成员的说明。<remarks> 标记是可以指定有关类或其他类型的概述信息的位置。<summary> 是可以描述该类型的成员的位置。<returns> <returns>description</returns>description 返回值的说明。<returns> 标记应当用于方法声明的注释，以描述返回值。<value> <value>property-description</value>property-description 属性的说明。<value> 标记使您得以描述属性。请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 <summary> 标记。然后，应该手动添加 <value> 标记以描述该属性所表示的值。3.2.5 代码行注释规范代码间注释分为单行注释和多行注释：单行注释样式：/<单行注释>多行注释如下所示：/* * * 功能说明 * */3.3其它规范3.3.1 基本变量定义前缘缩写规则序号名称缩写实例1boolblnblnAction2bytebytbytData3sbytesbytsbytData4charchrchrFirst5decimaldecdecNum6doubledbldblNum7floatfltfltCount8longlnglngLength9ulongulngulngLength10shortshtshtHeight11ushortushtushtHeight12stringstrstrName13DateTimedtmdtmFixedTime14objectobjobjLock15ArrayaryaryDatas16ListlstlstDatas3.3.2 WinFrom主要控件命名前缘缩写序号名称缩写控件说明1Labellbl标签2Buttonbyt按钮3TextBoxtxt输入框4LinkButtonlnkbtn超链接按钮5LinkLabellnklbl超链接标签6Imageimg图片基类7CheckBoxchk多选框8RadioButtonrbtn单选框9GroupBoxgbx组合框10PictureBoxpic图片框11Panelpnl容器12ComboBoxcbo组合框13ListViewlstv列表视图14TreeViewtrv树视图15Timertmr定时器控件16ImageListimglst17ToolTiptlp提示控件18ContextMenumnu右键菜单19ToolBartlb工具栏20StatusBarstb状态栏21RichTextBoxrtxt文本框22TabControltab切页控件3.3.3 WebFrom主要控件命名前缘缩写序号名称缩写控件说明1Labellbl标签2Buttonbyt按钮3TextBoxtxt输入框4LinkButtonlnkbtn超链接按钮5ImageButtonimgbtn6HyperLink7DropDownListddl8ListBoxlst9DataGriddgrp10DataListdlst11Repeaterrpt12CheckBoxchk13CheckBoxListchkl14RadioButtonListrdol15RadioButtonrdo16Imageimg17Panelpnl18PlaceHolderplh19Calendarcal日历控件20Tabletbl21RequireFieldValidatorvalr3.3.3 ADO.NET主要对象命名前缘缩写序号名称缩写控件说明1Connectioncon数据库连接对象2CommandcmdSql语句执行对象3DataAdapteradp4DataReaderdtr5DataSetds6DataTabledtbl7DataRowdr8DataColumndc9DataViewdv