《一站式示例代码库编程规范》由会员分享,可在线阅读,更多相关《一站式示例代码库编程规范(98页珍藏版)》请在金锄头文库上搜索。
1、一站式示例代码库编程规范作者:葛佳亮翻译:蒋里京本文档描述了微软一站式代码示例库项目组所采纳的关于本地 C+ 和 .NET (C# 和VB.NET)代码的编程风格指导规范。鸣谢本文档的每一章节都应该感谢Dan Ruder - 微软Principal Escalation Engineer 。 Dan 对本文档进行了斟字酌句的查阅,并根据其20余年的编程经验提供了大量的珍贵评论 。我很荣幸能与他共事。 我同样感谢微软的四位经理,感谢他们对该项目的一贯支持。他们是Vivian Luo,Allen Ding,Felix Wu 和 Mei Liang。 同时,如果没有如下一站式代码示例库项目的关键成员
2、的辛勤付出,本文档必定不会具有现在的技术深度以及完整度,我在这里要感谢他们:Hongye SunJie WangJi ZhouMichael SunKira QianLinda LiuAllen Chen Yi-Lun LuoSteven ChengWen-Jun Zhang本文档部分章节参考自一些微软产品组的编程规范。感谢他们的慷慨共享。本编程规范在不断改善。如果您发现某些最佳实践或者话题并没有涵盖在本文档中,请告知我们一站式示例代码库项目组 ,以不断充实改善本文档。我期待着您的参与。J声明本编程规范文档以“如是”提供,无论明示或暗示都不包含任何形式保证,但并不限制适用于特殊目的的默认担保。
3、 当您编写VC+/VC#/VB.NET 代码时,敬请参考或使用本文档。但是,我们希望您能通过告知我们您正在使用本文档,或给出任何改进建议。目录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.1
4、1函数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交互操作90Page 941 概览 本文档为一站式示例代码库项目组所使用的C+ 以及 .NET 编码规范 。该规范源自于产品开发过程中的经验,并在不断完善。如果您发现一些最佳实践或者话题并没有涵盖在本文档
5、中,请联系我们一站式示例代码库项目组 ,以不断充实完善本文档。任何指导准则都可能会众口难调。本规范的目的在于帮助社区开发者提高开发效率,减少代码中可能出现的bug,并增强代码的可维护性。万事开头难,采纳一个不熟悉的规范可能在初期会有一些棘手和困扰,但是这些不适应很快便会消失,它所带来的好处和优势很快便会显现,特别是在当您接手他人代码时。1.1 原则和主旨高质量的代码示例往往具有如下特质:1. 易懂 代码示例必须易读且简单明确。它们必须能展示出重点所在。示例代码的相关部分应当易于重用。示例代码不可包含多余代码。它们必须带有相应文档说明。2. 正确性 示例代码必须正确展示出其欲告知使用者的重点。代
6、码必须经过测试,且可以按照文档描述进行编译和运行。3. 一致性 示例代码应该按照一致的编程风格和设计来保证代码易读。 同样的,不同代码示例之间也应当保持一致的风格和设计,使使用者能够很轻松的结合使用它们。一致性将我们一站式示例代码库优良的品质形象传递给使用者,展示出我们对于细节的追求。4. 流行性 代码示例应当展示现行的编程实践,例如使用 Unicode,错误处理,防御式编程以及可移植性。示例代码应当使用当前推荐的运行时库和API函数,以及推荐的项目和生成设置。5. 可靠性 代码示例必须符合法律,隐私和政策标准和规范。不允许展示入侵性或低质的编程实践,不允许永久改变机器状态。所有的安装和执行过
7、程必须可以被撤销。6. 安全性 - 示例代码应该展示如何使用安全的编程实践 :例如最低权限原则,使用运行时库函数的安全版本,以及SDL推荐的项目设置。 合理使用编程实践,设计和语言特性决定了示例代码是否可以很好满足上述特性。本编程规范致力于帮助您创建代码示例以使使用者能够作为最佳实践来效仿和学习。1.2 术语在整个文档中,会有一些对于标准和实践的推荐和建议。一些实践是非常重要的,必须严格执行,另一些指导准则并不一定处处适用,但是会在特定的场景下带来益处。为了清楚陈述规范和实践的意图,我们会使用如下术语。术语意图理由 一定请.该规范或实践在任何情况下都应该遵守。如果您认为您的应用是例外,则可能不
8、适用。该规范用于减少bug。 一定不要.不允许应用该规范或实践。 您应该.该规范和实践适用于大多数情况。该规范用于统一编程风格,保持一致和清晰的风格。 您不应该.不应该应用该规范或实践,除非有合理的理由。 您可以该标准和规范您可以按需应用。该规范可用于编程风格,但不总是有益的。2 通用编程规范这些通用编程规范适用于所有语言 它们对代码风格,格式和结构提供了全局通用的指导。2.1 明确性和一致性 一定请确保代码的明确性,易读性和透明性。编程规范致力于确保代码是易懂和易维护的。没有什么胜于清晰、简洁、自描述的代码。 一定请确保 一旦应用了某编程规范,需在所有代码中应用,以保持一致性。 2.2 格式
9、和风格 一定不要使用制表符。不同的文字编辑器使用不同的空格来生成制表符 ,这就带来了格式混乱。所有代码都应该使用4个空格来表示缩进。可以配置Visual Studio 文字编辑器,以空格代替制表符 。 您应该 限制一行代码的最大长度。 过长的代码降低了代码易读性 。为了提高易读性,将代码长度设置为78列。若78列太窄,可以设置为86或者90。Visual C+ sample:Visual C# 示例:Visual Basic sample: 一定请 在您的代码编辑器中使用定宽字体,例如 Courier New。2.3 库的使用 一定不要 引用不必要的库,包括不必要的头文件,或引用不必要的程序集
10、。注重细节能够减少项目生成时间,最小化出错几率, 并给读者一个良好的印象。2.4 全局变量 一定请 尽量少用全局变量。 为了正确的使用全局变量,一般是将它们作为参数传入函数。永远不要在函数或类内部直接引用全局变量,因为这会引起一个副作用:在调用者不知情的情况下改变了全局变量的状态。这对于静态变量同样适用。如果您需要修改全局变量,您应该将其作为一个输出参数,或返回其一份全局变量的拷贝。 2.5 变量的声明和初始化 一定请在最小的,包含该局部变量的作用域块内声明它。一般,如果语言允许,就仅在使用前声明它们,否则就在作用域块的顶端声明。 一定请 在声明变量时初始化它们。 一定请 在语言允许的情况下,
11、将局部变量的声明和初始化或赋值置于同一行代码内。这减少了代码的垂直空间,确保了变量不会处在未初始化的状态。/ C+ sample:HANDLE hToken = NULL;PSID pIntegritySid = NULL;STARTUPINFO si = sizeof(si) ;PROCESS_INFORMATION pi = 0 ;/ C# sample:string name = myObject.Name;int val = time.Hours; VB.NET sample:Dim name As String = myObject.NameDim val As Integer =
12、time.Hours 一定不要 在同一行中声明多个变量 。推荐每行只包含一句声明,这样有利于添加注释,也减少歧义。例如 Visual C+ 示例,Good:CodeExample *pFirst = NULL; / Pointer of the first element.CodeExample *pSecond = NULL; / Pointer of the second element.Bad:CodeExample *pFirst, *pSecond;后一个代码示例经常被误写为:CodeExample *pFirst, pSecond;这种误写实际上等同于:CodeExample *p
13、First;CodeExample pSecond;2.6 函数的声明和调用 函数或方法的名称,返回值,参数列表可以有多种形式。原则上应该都将这些置于同一行代码内。如果带有过多参数不能置于一行代码,可以进行换行:多个参数一行或者一个参数一行。将返回值置于函数或方法名称的同一行。例如,单行格式:/ C+ function declaration sample:HRESULT DoSomeFunctionCall(int param1, int param2, int *param3);/ C+ / C# function call sample:hr = DoSomeFunctionCall(p
14、aram1, param2, param3); VB.NET function call sample:hr = DoSomeFunctionCall(param1, param2, param3)多行格式:/ C+ function declaration sample:HRESULT DoSomeFunctionCall(int param1, int param2, int *param3, int param4, int param5);/ C+ / C# function call sample:hr = DoSomeFunctionCall(param1, param2, param3, param4, param5); VB.NET function call sample:hr = DoSomeFunctionCall(param1, param2, param3, _ param4, param5)将参数列表置于多行代码时,每一个参数应该整齐排列