微软编程规范

目录1概览11.1原则和主旨11.2术语22通用编程规范32.1明确和一致32.2格式和风格32.3库的使用52.4全局变量52.5变量的声明和初始化62.6函数的声明和调用72.7语句82.8枚举92.9空格142.10大括号152.11注释172.12代码块263C++编程规范273.1编译器选项273.2文件和结构293.3命名规范303.4指针343.5常量343.6类型转换353.7Sizeof363.8字符串373.9数组383.10宏393.11函数403.12结构体433.13类443.14COM503.15动态分配513.16错误和异常523.17资源清理553.18控制流584.NET编码规范614.1类库开发设计规范614.2文件和结构614.3程序集属性614.4命名规范614.5常量654.6字符串654.7数组和集合674.8结构体694.9类704.10命名空间744.11错误和异常744.12资源清理774.13交互操作901概览本文档为一站式示例代码库项目组所使用的C++以及.NET编码规范。该规范源自于产品开发过程中的经验，并在不断完善。如果您发现一些最佳实践或者话题并没有涵盖在本文档中，请联系我们一站式示例代码库项目组，以不断充实完善本文档。任何指导准则都可能会众口难调。本规范的目的在于帮助社区开发者提高开发效率，减少代码中可能出现的bug，并增强代码的可维护性。万事开头难，采纳一个不熟悉的规范可能在初期会有一些棘手和困扰，但是这些不适应很快便会消失，它所带来的好处和优势很快便会显现，特别是在当您接手他人代码时。1.1原则和主旨高质量的代码示例往往具有如下特质:1.易懂–代码示例必须易读且简单明确。它们必须能展示出重点所在。示例代码的相关部分应当易于重用。示例代码不可包含多余代码。它们必须带有相应文档说明。2.正确性–示例代码必须正确展示出其欲告知使用者的重点。代码必须经过测试，且可以按照文档描述进行编译和运行。3.一致性–示例代码应该按照一致的编程风格和设计来保证代码易读。同样的，不同代码示例之间也应当保持一致的风格和设计，使使用者能够很轻松的结合使用它们。一致性将我们一站式示例代码库优良的品质形象传递给使用者，展示出我们对于细节的追求。4.流行性–代码示例应当展示现行的编程实践，例如使用Unicode，错误处理，防御式编程以及可移植性。示例代码应当使用当前推荐的运行时库和API函数，以及推荐的项目和生成设置。5.可靠性–代码示例必须符合法律，隐私和政策标准和规范。不允许展示入侵性或低质的编程实践，不允许永久改变机器状态。所有的安装和执行过程必须可以被撤销。6.安全性-示例代码应该展示如何使用安全的编程实践：例如最低权限原则，使用运行时库函数的安全版本，以及SDL推荐的项目设置。合理使用编程实践，设计和语言特性决定了示例代码是否可以很好满足上述特性。本编程规范致力于帮助您创建代码示例以使使用者能够作为最佳实践来效仿和学习。1.2术语在整个文档中，会有一些对于标准和实践的推荐和建议。一些实践是非常重要的，必须严格执行，另一些指导准则并不一定处处适用，但是会在特定的场景下带来益处。为了清楚陈述规范和实践的意图，我们会使用如下术语。术语意图理由一定请...该规范或实践在任何情况下都应该遵守。如果您认为您的应用是例外，则可能不适用。该规范用于减少bug。一定不要...不允许应用该规范或实践。您应该...该规范和实践适用于大多数情况。该规范用于统一编程风格，保持一致和清晰的风格。您不应该..不应该应用该规范或实践，除非有合理的理由。您可以…该标准和规范您可以按需应用。该规范可用于编程风格，但不总是有益的。2通用编程规范这些通用编程规范适用于所有语言–它们对代码风格，格式和结构提供了全局通用的指导。2.1明确性和一致性一定请确保代码的明确性，易读性和透明性。编程规范致力于确保代码是易懂和易维护的。没有什么胜于清晰、简洁、自描述的代码。一定请确保一旦应用了某编程规范，需在所有代码中应用，以保持一致性。2.2格式和风格一定不要使用制表符。不同的文字编辑器使用不同的空格来生成制表符，这就带来了格式混乱。所有代码都应该使用4个空格来表示缩进。可以配置VisualStudio文字编辑器，以空格代替制表符。您应该限制一行代码的最大长度。过长的代码降低了代码易读性。为了提高易读性，将代码长度设置为78列。若78列太窄，可以设置为86或者90。VisualC++sample:VisualC#示例:VisualBasicsample:一定请在您的代码编辑器中使用定宽字体，例如CourierNew。2.3库的使用一定不要引用不必要的库，包括不必要的头文件，或引用不必要的程序集。注重细节能够减少项目生成时间，最小化出错几率，并给读者一个良好的印象。2.4全局变量一定请尽量少用全局变量。为了正确的使用全局变量，一般是将它们作为参数传入函数。永远不要在函数或类内部直接引用全局变量，因为这会引起一个副作用：在调用者不知情的情况下改变了全局变量的状态。这对于静态变量同样适用。如果您需要修改全局变量，您应该将其作为一个输出参数，或返回其一份全局变量的拷贝。2.5变量的声明和初始化一定请在最小的，包含该局部变量的作用域块内声明它。一般，如果语言允许，就仅在使用前声明它们，否则就在作用域块的顶端声明。一定请在声明变量时初始化它们。一定请在语言允许的情况下，将局部变量的声明和初始化或赋值置于同一行代码内。这减少了代码的垂直空间，确保了变量不会处在未初始化的状态。//C++sample:HANDLEhToken=NULL;PSIDpIntegritySid=NULL;STARTUPINFOsi={sizeof（si）};PROCESS_INFORMATIONpi={0};//C#sample:stringname=myObject.Name;intval=time.Hours;'VB.NETsample:DimnameAsString=myObject.NameDimvalAsInteger=time.Hours一定不要在同一行中声明多个变量。推荐每行只包含一句声明，这样有利于添加注释，也减少歧义。例如VisualC++示例，Good:CodeExample*pFirst=NULL;//Pointerofthefirstelement.CodeExample*pSecond=NULL;//Pointerofthesecondelement.Bad:CodeExample*pFirst,*pSecond;后一个代码示例经常被误写为:CodeExample*pFirst,pSecond;这种误写实际上等同于:CodeExample*pFirst;CodeExamplepSecond;2.6函数的声明和调用函数或方法的名称，返回值，参数列表可以有多种形式。原则上应该都将这些置于同一行代码内。如果带有过多参数不能置于一行代码，可以进行换行：多个参数一行或者一个参数一行。将返回值置于函数或方法名称的同一行。例如,单行格式://C++functiondeclarationsample:HRESULTDoSomeFunctionCall（intparam1,intparam2,int*param3）;//C++/C#functioncallsample:hr=DoSomeFunctionCall（param1,param2,param3）;'VB.NETfunctioncallsample:hr=DoSomeFunctionCall（param1,param2,param3）多行格式://C++functiondeclarationsample:HRESULTDoSomeFunctionCall（intparam1,intparam2,int*param3,intparam4,intparam5）;//C++/C#functioncallsample:hr=DoSomeFunctionCall（param1,param2,param3,param4,param5）;'VB.NETfunctioncallsample:hr=DoSomeFunctionCall（param1,param2,param3,_param4,param5）将参数列表置于多行代码时，每一个参数应该整齐排列于前一个参数的下方。第一个类型/参数对置于新行行首，并缩进一个制表符宽度。函数或方法调用时的参数列表同样需按照这一格式。//C++sample:HRESULTDoSomeFunctionCall（HWNDhwnd,//Youcancommentparameters,tooT1param1,//IndicatessomethingT2param2,//IndicatessomethingelseT3param3,//IndicatesmoreT4param4,//IndicatesevenmoreT5param5）;//Yougettheidea//C++/C#sample:hr=DoSomeFunctionCall（hwnd,param1,param2,param3,param4,param5）;'VB.NETsample:hr=DoSomeFunctionCall（_hwnd,_param1,_param2,_param3,_param4,_param5）一定请将参数排序，并首先将输入参数分组，再将输出参数放置最后。在参数组内，按照能够帮助程序员输入正确值的原则来将参数排序。比如，如果一个函数带有2个参数，“left”和“right”，将“left”置于“right”之前，则它们的放置顺序符合其参数名。当设计一系列具有相同参数的函数时，在各函数内使用一致的顺序。比如，如果一个函数带有一个输入类型为句柄的参数作为第一参数，那么所有相关函数都应该将该输入句柄作为第一参数。2.7代码语句一定不要在同一行内放置一句以上的代码语句。这会使得调试器的单步调试变得更为困难。Good://C++/C#sample:a=1;b=2;'VB.NETsample:If（IsAdministrator（））ThenConsole.WriteLine（YES）EndIfBad://C++/C#sample:a=1;b=2;'VB.NETsample:If（IsAdministrator（））ThenConsole.WriteLine（YES）2.8枚举一定请将代表某些值集合的强类型参数，属性和返回值声明为枚举类型。一定请在合适的情况下尽量使用枚举类型，而不是静态常量或“#define”值。枚举类型是一个具有一个静态常量集合的结构体。如果遵守这些规范，定义枚举类型，而不是带有静态常量的结构体，您便会得到额外的编译器和反射支持。Good://C++sample:enumColor{Red,Green,Blue};//C#sample:publicenumColor{Red,Green,Blue}'VB.NETsample:PublicEnumColorRedGreenBlueEndEnumBad://C++sample:constintRED=0;constintGREEN=1;constintBLUE=2;#defineRED0#defineGREEN1#defineBLUE2//C#sample:publicstaticclassColor{publicconstintRed=0;publicconstintGreen=1;publicconstintBlue=2;}'VB.NETsample:PublicClassColorPublicConstRedAsInteger=0PublicConstGreenAsInteger=1PublicConstBlueAsInteger=2EndClass一定不要使用公开集合作为枚举（例如操作系统版本，您亲朋的姓名）。一定请为简单枚举提供一个0值