软件源代码编写与管理规范

软件源代码编写与管理规范软件代码编写规范第2页命名规则Net命名规则一致的命名模式是托管类库中可预知性与可发现性最重要的元素之一。对这些命名指南广泛的使用和理解将消除许多最常见的用户问题。本主题提供.NETFramework类型的命名指南。对于每个类型，还应该注意关于大写样式、区分大小写和措词的一些通用规则。大写样式描述用于在类库中命名标识符的Pascal大小写、Camel大小写和全部大写样式。使用下面的三种大写标识符约定。Pascal大小写将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用Pascal大小写。例如：BackColorCamel大小写标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：backColor大写标识符中的所有字母都大写。仅对于由两个或者更少字母组成的标识符使用该约定。例如：System.IOSystem.Web.UI可能还必须大写标识符以维持与现有非托管符号方案的兼容性，在该方案中所有大写字母经常用于枚举和常数值。一般情况下，在使用它们的程序集之外这些字符应当是不可见的。下表汇总了大写规则，并提供了不同类型的标识符的示例。标识符大小写示例类PascalAppDomain枚举类型PascalErrorLevel枚举值PascalFatalError事件PascalValueChange异常类PascalWebException注意

总是以Exception后缀结尾。只读的静态字段PascalRedValue接口PascalIDisposable注意

总是以I前缀开始。方法PascalToString命名空间PascalSystem.Drawing参数CameltypeName属性PascalBackColor受保护的实例字段CamelredValue注意

很少使用。属性优于使用受保护的实例字段。公共实例字段PascalRedValue注意

很少使用。属性优于使用公共实例字段。区分大小写为了避免混淆和保证跨语言交互操作，请遵循有关区分大小写的使用的下列规则：不要使用要求区分大小写的名称。对于区分大小写和不区分大小写的语言，组件都必须完全可以使用。不区分大小写的语言无法区分同一上下文中仅大小写不同的两个名称。因此，在创建的组件或类中必须避免这种情况。不要创建仅是名称大小写有区别的两个命名空间。例如，不区分大小写的语言无法区分以下两个命名空间声明。namespaceee.cummings;namespaceEe.Cummings;不要创建具有仅是大小写有区别的参数名称的函数。下面的示例是不正确的。voidMyFunction(stringa,stringA)不要创建具有仅是大小写有区别的类型名称的命名空间。在下面的示例中，Pointp和POINTp是不适当的类型名称，原因是它们仅在大小写方面有区别。System.Windows.Forms.PointpSystem.Windows.Forms.POINTp不要创建具有仅是大小写有区别的属性名称的类型。在下面的示例中，intColor和intCOLOR是不适当的属性名称，原因是它们仅在大小写方面有区别。intColor{get,set}intCOLOR{get,set}不要创建具有仅是大小写有区别的方法名称的类型。在下面的示例中，calculate和Calculate是不适当的方法名称，原因是它们仅在大小写方面有区别。voidcalculate()voidCalculate()缩写为了避免混淆和保证跨语言交互操作，请遵循有关区缩写的使用的下列规则：不要将缩写或缩略形式用作标识符名称的组成部分。例如，使用GetWindow，而不要使用GetWin。不要使用计算机领域中未被普遍接受的缩写。在适当的时候，使用众所周知的缩写替换冗长的词组名称。例如，用UI作为UserInterface的缩写，用OLAP作为On-lineAnalyticalProcessing的缩写。在使用缩写时，对于超过两个字符长度的缩写，请使用Pascal大小写或Camel大小写。例如，使用HtmlButton或htmlButton。但是，应当大写仅有两个字符的缩写，如，System.IO，而不是System.Io。不要在标识符或参数名称中使用缩写。如果必须使用缩写，对于由多于两个字符所组成的缩写请使用Camel大小写，虽然这和单词的标准缩写相冲突。措词避免使用与常用的.NETFramework命名空间重复的类名称。例如，不要将以下任何名称用作类名称：System、Collections、Forms或UI。有关.NETFramework命名空间的列表，请参见类库。另外，避免使用和以下关键字冲突的标识符。AddHandlerAddressOfAliasAndAnsiAsAssemblyAutoBaseBooleanByRefByteByValCallCaseCatchCBoolCByteCCharCDateCDecCDblCharCIntClassCLngCObjConstCShortCSngCStrCTypeDateDecimalDeclareDefault避免类型名称混淆语言不同的编程语言使用不同的术语标识基本托管类型。类库设计人员必须避免使用语言特定的术语。请遵循本节中描述的规则以避免类型名称混淆。使用描述类型的含义的名称，而不是描述类型的名称。如果参数除了其类型之外没有任何语义含义，那么在这种罕见的情况下请使用一般性名称。例如，支持将各种数据类型写入到流中的类可以有以下方法。voidWrite(doublevalue);voidWrite(floatvalue);voidWrite(longvalue);voidWrite(intvalue);voidWrite(shortvalue);不要创建语言特定的方法名称，如下面的示例所示。voidWrite(doubledoubleValue);voidWrite(floatfloatValue);voidWrite(longlongValue);voidWrite(intintValue);voidWrite(shortshortValue);如果有必要为每个基本数据类型创建唯一命名的方法，那么在这种极为罕见的情况下请使用通用类型名称。下表列出基本数据类型名称和它们的通用替换。C#类型名称JScript类型名称VisualC++类型名称通用类型名称sbytesBytecharSBytebytebyteunsignedcharByteshortshortshortInt16ushortushortunsignedshortUInt16intintintInt32uintuintunsignedintUInt32longlong__int64Int64ulongulongunsigned__int64UInt64floatfloatfloatSingledoubledoubledoubleDoubleboolbooleanboolBooleancharcharwchar_tCharstringstringStringStringobjectobjectObjectObject例如，支持将从流读取各种数据类型的类可以有以下方法。doubleReadDouble();floatReadSingle();longReadInt64();intReadInt32();shortReadInt16();上面的示例优先于下面的语言特定的替代方法。doubleReadDouble();floatReadFloat();longReadLong();intReadInt();shortReadShort();命名空间命名指南命名命名空间时的一般性规则是使用公司名称，后跟技术名称和可选的功能与设计，如下所示。CompanyName.TechnologyName[.Feature][.Design]例如：Microsoft.MediaMicrosoft.Media.Design给命名空间名称加上公司名称或者其他知名商标的前缀可以避免两个已经发布的命名空间名称相同的可能性。例如，Microsoft.Office是由Microsoft提供的OfficeAutomationClasses的一个适当的前缀。在第二级分层名称上使用稳定的、公认的技术名称。将组织层次架构用作命名空间层次架构的基础。命名一个命名空间，该命名空间包含为具有.Design后缀的基命名空间提供设计时功能的类型。例如，System.Windows.Forms.Design命名空间包含用于设计基于System.Windows.Forms的应用程序的设计器和相关的类。嵌套的命名空间应当在包含它的命名空间中的类型上有依赖项。例如，System.Web.UI.Design中的类依赖于System.Web.UI中的类。但是，System.Web.UI中的类不依赖于System.Web.UI.Design中的类。应当对命名空间使用Pascal大小写，并用句点分隔逻辑组件，如Microsoft.Office.PowerPoint中所示。如果您的商标使用非传统的大小写，请遵循您的商标所定义的大小写，即使它与规定的Pascal大小写相背离。例如，命名空间NeXT.WebObjects和ee.cummings阐释了对于Pascal大小写规则的适当背离。如果在语义上适当，使用复数命名空间名称。例如，使用System.Collections而不是System.Collection。此规则的例外是商标名称和缩写。例如，使用System.IO而不是System.IOs。不要为命名空间和类使用相同的名称。例如，不要既提供Debug命名空间也提供Debug类。最后，请注意命名空间名称不必非得与程序集名称相似。例如，如果命名程序集MyCompany.MyTechnology.dll，它没有必要非得包含MyCompany.MyTechnology命名空间。类命名指南以下规则概述命名类的指南：使用名词或名词短语命名类。使用Pascal大小写。少用缩写。不要使用类型前缀，如在类名称上对类使用C前缀。例如，使用类名称FileStream，而不是CFileStream。不要使用下划线字符(_)。有时候需要提供以字母I开始的类名称，虽然该类不是接口。只要I是作为类名称组成部分的整个单词的第一个字母，这便是适当的。例如，类名称IdentityStore就是适当的。在适当的地方，使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。例如，ApplicationException对于从名为Exception的类派生的类是适当的名称，原因是ApplicationException是一种Exception。请在应用该规则时进行合理的判断。例如，Button对于从Control派生的类是适当的名称。尽管按钮是一种控件，但是将Control作为类名称的一部分将使名称不必要地加长。下面是正确命名的类的示例。publicclassFileStreampublicclassButtonpublicclassString接口命名指南以下规则概述接口的命名指南：用名词或名词短语，或者描述行为的形容词命名接口。例如，接口名称IComponent使用描述性名词。接口名称ICustomAttributeProvider使用名词短语。名称IPersistable使用形容词。使用Pascal大小写。少用缩写。给接口名称加上字母I前缀，以指示该类型为接口。在定义类/接口对（其中类是接口的标准实现）时使用相似的名称。两个名称的区别应该只是接口名称上有字母I前缀。不要使用下划线字符(_)。以下是正确命名的接口的示例。publicinterfaceIServiceProviderpublicinterfaceIFormatable以下代码示例阐释如何定义IComponent接口及其标准实现Component类。publicinterfaceIComponent{//Implementationcodegoeshere.}publicclassComponent:IComponent{//Implementationcodegoeshere.}属性命名指南应该总是将后缀Attribute添加到自定义属性类。以下是正确命名的属性类的示例。publicclassObsoleteAttribute{}枚举类型命名指南枚举(Enum)值类型从Enum类继承。以下规则概述枚举的命名指南：对于Enum类型和值名称使用Pascal大小写。少用缩写。不要在Enum类型名称上使用Enum后缀。对大多数Enum类型使用单数名称，但是对作为位域的Enum类型使用复数名称。总是将FlagsAttribute添加到位域Enum类型。静态字段命名指南以下规则概述静态字段的命名指南：使用名词、名词短语或者名词的缩写命名静态字段。使用Pascal大小写。不要在静态字段名称中使用匈牙利语表示法的前缀。建议尽可能使用静态属性而不是公共静态字段。参数命名指南必须仔细遵守这些参数的命名指南，这非常重要，因为提供上下文相关帮助和类浏览功能的可视化设计工具会在设计器中对用户显示方法参数名称。以下规则概述参数的命名指南：对参数名称使用Camel大小写。使用描述性参数名称。参数名称应当具有足够的描述性，以便参数的名称及其类型可用于在大多数情况下确定它的含义。例如，提供上下文相关帮助的可视化设计工具会按开发人员键入的实际内容显示方法参数。在这种情况下，方法参数名称的表述必须清楚明白，开发人员才能提供正确的参数。使用描述参数的含义的名称，而不要使用描述参数的类型的名称。开发工具将提供有关参数的类型的有意义的信息。因此，通过描述意义，可以更好地使用参数的名称。少用基于类型的参数名称，仅在适合使用它们的地方使用它们。不要使用保留的参数。保留的参数是专用参数，如果需要，可以在未来的版本中公开它们。相反，如果在类库的未来版本中需要更多的数据，请为方法添加新的重载。以下是正确命名的参数的示例。TypeGetType(stringtypeName)stringFormat(stringformat,object[]args)方法命名指南以下规则概述方法的命名指南：使用动词或动词短语命名方法。使用Pascal大小写。以下是正确命名的方法的实例。RemoveAll()GetCharArray()Invoke()属性命名指南以下规则概述属性的命名指南：使用名词或名词短语命名属性。使用Pascal大小写。考虑用与属性的基础类型相同的名称创建属性。例如，如果声明名为Color的属性，则属性的类型同样应该是Color。以下代码示例阐释正确的属性命名。publicclassSampleClass{publicColorBackColor{//CodeforGetandSetaccessorsgoeshere.}}以下代码示例阐释提供其名称与类型相同的属性。publicenumColor{//InsertcodeforEnumhere.}publicclassControl{publicColorColor{get{//Insertcodehere.}set{//Insertcodehere.}}}以下代码示例不正确，原因是Color属性是Integer类型的。publicenumColor{//InsertcodeforEnumhere.}publicclassControl{publicintColor{get{//Insertcodehere.}set{//Insertcodehere.}}}在不正确的示例中，不可能引用Color枚举的成员。Color.Xxx将被解释为访问一个成员，该成员首先获取Color属性（在VisualBasic中为Integer类型，在C#中为int类型）的值，然后再访问该值的某个成员（该成员必须是System.Int32的实例成员）。事件命名指南以下规则概述事件的命名指南：使用Pascal大小写。对事件处理程序名称使用EventHandler后缀。指定两个名为sender和e的参数。sender参数表示引发事件的对象。sender参数始终是object类型的，即使在可以使用更为特定的类型时也如此。与事件相关联的状态封装在名为e的事件类的实例中。对e参数类型使用适当而特定的事件类。用EventArgs后缀命名事件参数类。考虑用动词命名事件。例如，命名正确的事件名称包括Clicked、Painting和DroppedDown。使用动名词（动词的“ing”形式）创建表示事件前的概念的事件名称，用过去式表示事件后。例如，可以取消的Close事件应当具有Closing事件和Closed事件。不要使用BeforeXxx/AfterXxx命名模式。不要在类型的事件声明上使用前缀或者后缀。例如，使用Close，而不要使用OnClose。通常情况下，对于可以在派生类中重写的事件，应在类型上提供一个受保护的方法（称为OnXxx）。此方法只应具有事件参数e，因为发送方总是类型的实例。以下示例阐释具有适当名称和参数的事件处理程序。publicdelegatevoidMouseEventHandler(objectsender,MouseEventArgse);以下示例阐释正确命名的事件参数类。publicclassMouseEventArgs:EventArgs{intx;inty;publicMouseEventArgs(intx,inty){this.x=x;this.y=y;}publicintX{get{returnx;}}publicintY{get{returny;}}}SQLServer命名规则在SQLSERVER中标识符共有两种类型:一种是规则标识符(Regularidentifer)，一种是界定标识符(Delimitedidentifer)。其中，规则标识符严格遵守标识符的有关格式的规定，所以在Transact_SQL中凡是规则运算符都不必使用定界符。对于不符合标识符格式的标识符要使用界定符[]或''。标识符格式:标识符必须是统一码(Unicode)2.0标准中规定的字符，以及其他一些语言字符。如汉字.标识符后的字符可以是(除条件一)“_”、“@”、“#”、“$”及数字。标识符不允许是Transact-SQL的保留字。标识符内不允许有空格和特殊字符。另外，某些以特殊符号开头的标识符在SQLSERVER中具有特定的含义。如以“@”开头的标识符表示这是一个局部变量或是一个函数的参数;以#开头的标识符表示这是一个临时表或是一存储过程。以“##”开头的表示这是一个全局的临时数据库对象。Transact-SQL的全局变量以“@@”开头。标识符最多可以容纳128个字符。数据表命名规则在命名表时，使用Pascal大小写；连接的单词间用“_”隔开。例如，Person_Balance用单数形式表示名称。例如，使用Employee，而不是Employees。不要在列的名称中包含数据类型。数据视图命名规则在命名表时，使用Pascal大小写；连接的单词间用“_”隔开。视图以“View_”前缀命名。命名内容中建议包含主表名称。例如：View_Personnel；数据字段命名规则在命名表时，使用Pascal大小写；连接的单词间用“_”隔开。主键或自增长标示字段尽量采用“ID”命名外键字段采用“表名”+“ID”模式命名，例如：PersonnelID触发器命名规则触发器命名采用“TRI_”为前缀命名在命名表时，使用Pascal大小写；连接的单词间用“_”隔开。触发器命名中建议包含触发器表名和触发方式。例如：TRI_Personnel_INS(Personnel表插入时的触发器)或者TRI_Personnel_All(Personnel表插入、修改、删除触发器)存储过程命名规则在命名表时，使用Pascal大小写；连接的单词间用“_”隔开。命名时采用过程意义命名，如：Calculate_Personnel_Balance。允许增加前缀：“Proc_”。变量命名规则在命名表时，使用Pascal大小写；例如：Declare@PersonnalIDint游标变量采用“Cur”前缀，例如：CurPersonnel注释软件文档以两种形式存在：外部的和内部的。外部文档（如规范、帮助文件和设计文档）在源代码的外部维护。内部文档由开发人员在开发时在源代码中编写的注释组成。不考虑外部文档的可用性，由于硬拷贝文档可能会放错地方，源代码清单应该能够独立存在。外部文档应该由规范、设计文档、更改请求、错误历史记录和使用的编码标准组成。内部软件文档的一个难题是确保注释的维护与更新与源代码同时进行。尽管正确注释源代码在运行时没有任何用途，但这对于必须维护特别复杂或麻烦的软件片段的开发人员来说却是无价的。以下几点是推荐的注释方法：如果用C#进行开发，请使用XML文档功能。有关更多信息，请参见：XML文档。修改代码时，总是使代码周围的注释保持最新。在每个例程的开始，提供标准的注释样本以指示例程的用途、假设和限制很有帮助。注释样本应该是解释它为什么存在和可以做什么的简短介绍。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释在公共制表位处对齐。避免杂乱的注释，如一整行星号。而是应该使用空白将注释同代码分开。避免在块注释的周围加上印刷框。这样看起来可能很漂亮，但是难于维护。在部署之前，移除所有临时或无关的注释，以避免在日后的维护工作中产生混乱。如果需要用注释来解释复杂的代码节，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能，但必须保持性能和可维护性之间的平衡。在编写注释时使用完整的句子。注释应该阐明代码，而不应该增加多义性。在编写代码时就注释，因为以后很可能没有时间这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。注释代码中不十分明显的任何内容。为了防止问题反复出现，对错误修复和解决方法代码总是使用注释，尤其是在团队环境中。对由循环和逻辑分支组成的代码使用注释。这些是帮助源代码读者的主要方面。在整个应用程序中，使用具有一致的标点和结构的统一样式来构造注释。用空白将注释同注释分隔符分开。在没有颜色提示的情况下查看注释时，这样做会使注释很明显且容易被找到。XML文档编译器将处理任何为有效XML的标记。下列标记提供了用户文档中常用的功能：<c><para><see><code><param><seealso><example><paramref><summary><exception><permission><value><include><remarks>

<list><returns>

描述标记<summary>语法:<summary>description</summary>其中:description对象的摘要。备注<summary>标记应当用于描述类型或类型成员。使用<remarks>添加针对某个类型说明的补充信息。有关<summary>标记的文本是关于智能感知中类型信息的唯一来源，并且也显示在对象浏览器和代码注释Web报表中。示例//xml_summary_tag.cs//compilewith:/doc:xml_summary_tag.xml///textforclassMyClasspublicclassMyClass{///<summary>MyMethodisamethodintheMyClassclass.///<para>Here'showyoucouldmakeasecondparagraphinadescription.<seecref="System.Console.WriteLine"/>forinformationaboutoutputstatements.</para>///<seealsocref="MyClass.Main"/>///</summary>publicstaticvoidMyMethod(intInt1){}///textforMainpublicstaticvoidMain(){}}详述标记<remarks>语法<remarks>description</remarks>其中description成员的说明。备注<remarks>标记用于添加有关某个类型的信息，从而补充由<summary>所指定的信息。此信息将显示在对象浏览器和代码注释Web报表中。示例//xml_remarks_tag.cs//compilewith:/doc:xml_remarks_tag.xml///<summary>///Youmayhavesomeprimaryinformationaboutthisclass.///</summary>///<remarks>///Youmayhavesomeadditionalinformationaboutthisclass.///</remarks>publicclassMyClass{///textforMainpublicstaticvoidMain(){}}参数说明<param>语法<paramname='name'>description</param>其中name方法参数名。将此名称用单引号括起来('')。description参数说明。备注<param>标记应当用于方法声明的注释中，以描述方法的一个参数。有关<param>标记的文本将显示在智能感知、对象浏览器和代码注释Web报表中。示例//xml_param_tag.cs//compilewith:/doc:xml_param_tag.xml///textforclassMyClasspublicclassMyClass{///<paramname="Int1">Usedtoindicatestatus.</param>publicstaticvoidMyMethod(intInt1){}///textforMainpublicstaticvoidMain(){}}返回说明<returns>语法<returns>description</returns>其中description返回值的说明。备注<returns>标记应当用于方法声明的注释，以描述返回值。示例//xml_returns_tag.cs//compilewith:/doc:xml_returns_tag.xml///textforclassMyClasspublicclassMyClass{///<returns>Returnszero.</returns>publicstaticintGetZero(){return0;}///textforMainpublicstaticvoidMain(){}}举例标记<example>语法<example>description</example>其中description代码示例的说明。备注使用<example>标记可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到<code>标记的使用。示例//xml_example_tag.cs//compilewith:/doc:xml_ctag.xml///textforclassMyClasspublicclassMyClass{///<summary>///TheGetZeromethod.///</summary>///<example>ThissampleshowshowtocalltheGetZeromethod.///<code>///classMyClass///{///publicstaticintMain()///{///returnGetZero();///}///}///</code>///</example>publicstaticintGetZero(){return0;}///textforMainpublicstaticvoidMain(){}}异常说明<exception>语法<exceptioncref="member">description</exception>其中cref="member"对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将member转换为输出XML中的规范化元素名。必须将member括在双引号("")中。description说明。备注<exception>标记使您可以指定哪些异常可被引发。该标记应用于方法定义。使用/doc进行编译可以将文档注释处理到文件中。示例//xml_exception_tag.cs//compilewith:/doc:xml_exception_tag.xmlusingSystem;///commentforclasspublicclassEClass:Exception{//classdefinition...}///<exceptioncref="System.Exception">Thrownwhen....</exception>classTestClass{publicstaticvoidMain(){try{}catch(EClass){}}}属性说明<value>语法<value>property-description</value>其中property-description属性的说明。备注<value>标记使您得以描述属性。请注意，当在VisualStudio.NET开发环境中通过代码向导添加属性时，它将会为新属性添加<summary>标记。然后，应该手动添加<value>标记以描述该属性所表示的值。示例//xml_value_tag.cs//compilewith:/doc:xml_value_tag.xmlusingSystem;///textforclassEmployeepublicclassEmployee{privatestringname;///<value>Nameaccessesthevalueofthenamedatamember</value>publicstringName{get{returnname;}set{name=value;}}}///textforclassMainClasspublicclassMainClass{///textforMainpublicstaticvoidMain(){}}举例: ///<summary>///列举某一数据库的工位点。///第一次调用该函数时Tag.nTagID=0,后续的调用需要传入上次返回的nTagID,Tag.sTagName为返回的设备名///在调用本函数之前，需要调用GetTagsByDevice或者GetTagsByNameMask函数,先取得点的集合。///</summary>///<paramname="hRecordset">传入参数,数据库类型标志/// 如果要列举Agilor的点，hRecordset的值为0到RAND_MAX之间的值/// 如果要列举InfoPlus的点，hRecordset的值为C_IP_RECORDSET_HANDLE/// 如果要列举PI的点，hRecordset的值为C_PI_RECORDSET_HANDLE///</param> ///<paramname="tag">传出参数,数据库工位点信息///</param> ///<returns>大于等于=0表示成功,-1表示没有可枚举的点</returns>intEnumTagName(longhRecordset,Tag*tag){ _TCHARszTagName[C_FULL_TAGNAME_LEN]; intnRes; 。。。。。}其他设计文档中的注释1、函数头的注释对于函数，应该从“功能”，“参数”，“返回值”、“主要思路”、“调用方法”、“日期”六个方面用如下格式注释：

/*程序说明开始

================================================================

功能：从一个String中删除另一个String。

参数：strByDelete,strToDelete

（入口）strByDelete:被删除的字符串（原来的字符串）

（出口）strToDelete:要从上个字符串中删除的字符串。

返回：找到并删除返回1，否则返回0。（对返回值有错误编码的要//求列出错误编码）。

主要思路：本算法主要采用循环比较的方法来从strByDelete中找到

与st