软件代码编写规范

软件代码编写规范草稿1命名规则命名规则一致的命名模式是托管类库中可预知性与可发现性最重要的元素之一。对这些命名指南广泛的使用和理解将消除许多最常见的用户问题。本主题提供.NETFramework类型的命名指南。对于每个类型，还应该注意关于大写样式、区分大小写和措词的一些通用规则。1.1.1大写样式描述用于在类库中命名标识符的Pascal大小写、Camel大小写和全部大写样式。使用下面的三种大写标识符约定。Pascal大小写将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用Pascal大小写。例如：BackColorCamel大小写标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：backColor大写标识符中的所有字母都大写。仅对于由两个或者更少字母组成的标识符使用该约定。例如：可能还必须大写标识符以维持与现有非托管符号方案的兼容性，在该方案中所有大写字母经常用于枚举和常数值。一般情况下，在使用它们的程序集之外这些字符应当是不可见的。下表汇总了大写规则，并提供了不同类型的标识符的示例。标识符大小写示例类PascalAppDomain枚举类型PascalErrorLevel枚举值PascalFatalError事件PascalValueChange异常类PascalWebException注意总是以Exception后缀结尾。只读的静态字段PascalRedValue接口PascalIDisposable注意总是以I前缀开始。方法PascalToString命名空间Pascal参数CameltypeName属性PascalBackColor受保护的实例字段CamelredValue注意很少使用。属性优于使用受保护的实例字段。公共实例字段PascalRedValue注意很少使用。属性优于使用公共实例字段。1.1.2区分大小写为了避免混淆和保证跨语言交互操作，请遵循有关区分大小写的使用的下列规则：不要使用要求区分大小写的名称。对于区分大小写和不区分大小写的语言，组件都必须完全可以使用。不区分大小写的语言无法区分同一上下文中仅大小写不同的两个名称。因此，在创建的组件或类中必须避免这种情况。不要创建仅是名称大小写有区别的两个命名空间。例如，不区分大小写的语言无法区分以下两个命名空间声明。namespace;namespace;不要创建具有仅是大小写有区别的参数名称的函数。下面的示例是不正确的。voidMyFunction(stringa,stringA)不要创建具有仅是大小写有区别的类型名称的命名空间。在下面的示例中，Pointp和POINTp是不适当的类型名称，原因是它们仅在大小写方面有区别。pp不要创建具有仅是大小写有区别的属性名称的类型。在下面的示例中，intColor和intCOLOR是不适当的属性名称，原因是它们仅在大小写方面有区别。intColor{get,set}intCOLOR{get,set}不要创建具有仅是大小写有区别的方法名称的类型。在下面的示例中，calculate和Calculate是不适当的方法名称，原因是它们仅在大小写方面有区别。voidcalculate()voidCalculate()1.1.3缩写为了避免混淆和保证跨语言交互操作，请遵循有关区缩写的使用的下列规则：不要将缩写或缩略形式用作标识符名称的组成部分。例如，使用GetWindow，而不要使用GetWin。不要使用计算机领域中未被普遍接受的缩写。在适当的时候，使用众所周知的缩写替换冗长的词组名称。例如，用UI作为UserInterface的缩写，用OLAP作为On-lineAnalyticalProcessing的缩写。在使用缩写时，对于超过两个字符长度的缩写，请使用Pascal大小写或Camel大小写。例如，使用HtmlButton或htmlButton。但是，应当大写仅有两个字符的缩写，如，，而不是。不要在标识符或参数名称中使用缩写。如果必须使用缩写，对于由多于两个字符所组成的缩写请使用Camel大小写，虽然这和单词的标准缩写相冲突。1.1.4措词避免使用与常用的.NETFramework命名空间重复的类名称。例如，不要将以下任何名称用作类名称：System、Collections、Forms或UI。有关.NETFramework命名空间的列表，请参见类库。另外，避免使用和以下关键字冲突的标识符。AddHandlerAddressOfAliasAndAnsiAsAssemblyAutoBaseBooleanByRefByteByValCallCaseCatchCBoolCByteCCharCDateCDecCDblCharCIntClassCLngCObjConstCShortCSngCStrCTypeDateDecimalDeclareDefault1.1.5避免类型名称混淆语言不同的编程语言使用不同的术语标识基本托管类型。类库设计人员必须避免使用语言特定的术语。请遵循本节中描述的规则以避免类型名称混淆。使用描述类型的含义的名称，而不是描述类型的名称。如果参数除了其类型之外没有任何语义含义，那么在这种罕见的情况下请使用一般性名称。例如，支持将各种数据类型写入到流中的类可以有以下方法。[VisualBasic]SubWrite(valueAsDouble);SubWrite(valueAsSingle);SubWrite(valueAsLong);SubWrite(valueAsInteger);SubWrite(valueAsShort);[C#]voidWrite(doublevalue);voidWrite(floatvalue);voidWrite(longvalue);voidWrite(intvalue);voidWrite(shortvalue);不要创建语言特定的方法名称，如下面的示例所示。[VisualBasic]SubWrite(doubleValueAsDouble);SubWrite(singleValueAsSingle);SubWrite(longValueAsLong);SubWrite(integerValueAsInteger);SubWrite(shortValueAsShort);[C#]voidWrite(doubledoubleValue);voidWrite(floatfloatValue);voidWrite(longlongValue);voidWrite(intintValue);voidWrite(shortshortValue);如果有必要为每个基本数据类型创建唯一命名的方法，那么在这种极为罕见的情况下请使用通用类型名称。下表列出基本数据类型名称和它们的通用替换。C#类型名称VisualBasic类型名称JScript类型名称VisualC++类型名称表示形式通用类型名称sbyteSBytesBytecharint8SBytebyteBytebyteunsignedcharunsignedint8ByteshortShortshortshortint16Int16ushortUInt16ushortunsignedshortunsignedint16UInt16intIntegerintintint32Int32uintUInt32uintunsignedintunsignedint32UInt32longLonglong__int64int64Int64ulongUInt64ulongunsigned__int64unsignedint64UInt64floatSinglefloatfloatfloat32SingledoubleDoubledoubledoublefloat64DoubleboolBooleanbooleanboolboolBooleancharCharcharwchar_tcharCharstringStringstringStringstringStringobjectObjectobjectObjectobjectObject例如，支持将从流读取各种数据类型的类可以有以下方法。[VisualBasic]ReadDouble()AsDoubleReadSingle()AsSingleReadInt64()AsLongReadInt32()AsIntegerReadInt16()AsShort[C#]doubleReadDouble();floatReadSingle();longReadInt64();intReadInt32();shortReadInt16();上面的示例优先于下面的语言特定的替代方法。[VisualBasic]ReadDouble()AsDoubleReadSingle()AsSingleReadLong()AsLongReadInteger()AsIntegerReadShort()AsShort[C#]doubleReadDouble();floatReadFloat();longReadLong();intReadInt();shortReadShort();1.1.6命名空间命名指南命名命名空间时的一般性规则是使用公司名称，后跟技术名称和可选的功能与设计，如下所示。[.Feature][.Design]例如：给命名空间名称加上公司名称或者其他知名商标的前缀可以避免两个已经发布的命名空间名称相同的可能性。例如，是由Microsoft提供的OfficeAutomationClasses的一个适当的前缀。在第二级分层名称上使用稳定的、公认的技术名称。将组织层次架构用作命名空间层次架构的基础。命名一个命名空间，该命名空间包含为具有.Design后缀的基命名空间提供设计时功能的类型。例如，命名空间包含用于设计基于的应用程序的设计器和相关的类。嵌套的命名空间应当在包含它的命名空间中的类型上有依赖项。例如，中的类依赖于中的类。但是，中的类不依赖于中的类。应当对命名空间使用Pascal大小写，并用句点分隔逻辑组件，如中所示。如果您的商标使用非传统的大小写，请遵循您的商标所定义的大小写，即使它与规定的Pascal大小写相背离。例如，命名空间和阐释了对于Pascal大小写规则的适当背离。如果在语义上适当，使用复数命名空间名称。例如，使用而不是。此规则的例外是商标名称和缩写。例如，使用而不是。不要为命名空间和类使用相同的名称。例如，不要既提供Debug命名空间也提供Debug类。最后，请注意命名空间名称不必非得与程序集名称相似。例如，如果命名程序集，它没有必要非得包含命名空间。推荐使用的命名空间1.1.7类命名指南以下规则概述命名类的指南：使用名词或名词短语命名类。使用Pascal大小写。少用缩写。不要使用类型前缀，如在类名称上对类使用C前缀。例如，使用类名称FileStream，而不是CFileStream。不要使用下划线字符(_)。有时候需要提供以字母I开始的类名称，虽然该类不是接口。只要I是作为类名称组成部分的整个单词的第一个字母，这便是适当的。例如，类名称IdentityStore就是适当的。在适当的地方，使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。例如，ApplicationException对于从名为Exception的类派生的类是适当的名称，原因是ApplicationException是一种Exception。请在应用该规则时进行合理的判断。例如，Button对于从Control派生的类是适当的名称。尽管按钮是一种控件，但是将Control作为类名称的一部分将使名称不必要地加长。下面是正确命名的类的示例。[VisualBasic]PublicClassFileStreamPublicClassButtonPublicClassString[C#]publicclassFileStreampublicclassButtonpublicclassString1