C++编程规范101条规则与最佳实践0.pdf

组织和策略问题 如果人们按照程序员编程的方式修建房屋，那么一只啄木鸟就能毁灭整个文明。Gerald Weinberg 为了遵从 C 和 C+的伟大传统，我们从 0 开始编号。首要的指导原则，也就是第 0 条，阐明了我们认为对编程规范而言最为基本的建议。接下来，这个导论性部分的其他条款将主要讲述几个精心选择的基本问题，这些问题大多数与代码本身并没有直接关系，它们讨论的是编写坚实代码所必需的工具和技术。本部分中我们选出的最有价值条款是第 0 条：“不要拘泥于小节”（又名：“了解哪些东西不应该标准化”）。Gerald Weinberg 是著名的软件思想家（他自称 thinker），因程序开发心理学等书名世，以对软件开发的深刻洞察而著称。译者注 2 C+编程规范：101 条规则、准则与最佳实践 第 0 条 不要拘泥于小节（又名：了解哪些东西不应该标准化）摘要 只规定需要规定的事情：不要强制施加个人喜好或者过时的做法。讨论 有些问题只是个人喜好，并不影响程序的正确性或者可读性，所以这些问题不应该出现在编程规范中。任何专业程序员都可以很容易地阅读和编写与其习惯的格式略有不同的代码。应该在每个源文件乃至每个项目中都使用一致的格式，因为同一段代码中要在几种编程风格（style）之间换来换去是很不舒服的。但是无需在多个项目或者整个公司范围内强制实施一致的格式。下面列举了几种常见的情况，在这里重要的不是设定规则，而是与所维护的文件中已经使用的体例保持一致。不要规定缩进多少，应该规定要用缩进来体现代码的结构。缩进空格的数量可以遵照个人习惯，但是至少在每个文件中应该保持一致。不要强制行的具体长度，应该保证代码行的长度有利于阅读。可以遵照个人习惯来决定行长，但是不要过长。研究表明，文字长度不超过 10 个单词最利于阅读。不要在命名方面规定过多，应该规定的是使用一致的命名规范。只有两点是必需的：（1）永远不要使用“晦涩的名称”，即以下划线开始或者包含双下划线的名称；（2）总是使用形如 ONLY_UPPERCASE_NAMES 的全大写字母表示宏，不要考虑使用常见的词或者缩略语作为宏的名称（包括常见的模板参数，比如 T 和 U；像#define T anything 这样的代码是极容易混淆的）。此外，应该使用一致的、有意义的名称，遵循文件的或者模块的规范。（如果你无法决定自己的命名规范，可以尝试如下命名规则：类、函数和枚举的名称形如LikeThis，即单词首字母大写；变量名形如 likeThis，即第一个单词首字母小写，第二个单词首字母大写；私有成员变量名形如 likeThis_；宏名称形如 LIKE_THIS。）不要规定注释风格（除非需要使用工具从特定的体例中提取出文档），应该编写有用的注释。尽可能编写代码而不是写注释（比如，见第 16 条）。不要在注释中重复写代码语义，这样很容易产生不一致。应该编写的是解释方法和原理的说明性注释。最后，不要尝试强制实施过时的规则（见例 3 和例 4），即使它们曾经在一些比较陈旧的编程规范中出现过。示例 出自 Richard Carlson 的畅销书 Dont Sweat the Small Stuff and Its all Small Stuff，中文版译名为别为小事 抓狂。译者注 组织和策略问题 3 例 1 大括号的位置。以下代码在可读性方面并不存在区别：void using_k_and_r_style()/void putting_each_brace_on_its_own_line()/void or_putting_each_brace_on_its_own_line_indented()/任何一个专业程序员都能够毫无困难地阅读和编写这些体例中的任何一种。但是应该保持一致：不要随意地或者以容易混淆作用域嵌套关系的方式放置大括号，要尽量遵循每个文件中已经使用的体例。在本书中，对大括号位置的选择主要是为了能够在编辑允许范围内得到最佳可读性。例 2 空格与制表符。有些团队禁用制表符（比如BoostLRG），因为不同的编辑器中制表符的设定是不同的，如果使用不当，会将缩进变为“缩出”和“无缩进”。其他同样受人尊敬的团队则允许使用制表符，并采取了一些能够避免其潜在缺陷的规定。这都是合理的，其实只要保持一致即可：如果允许使用制表符，那么要确保团队成员维护彼此的代码时，不会影响代码的清晰和可读性（见第 6 条）。如果不允许使用制表符，应该允许编辑器在读入源文件时将空格转换为制表符，使用户能够在编辑器中使用制表符，但是在将文件写回时，一定要将制表符转换回空格。例 3 匈牙利记法。将类型信息并入变量名的记法，是混用了类型不安全语言（特别是 C）中的设施，这在面向对象语言中是可以存在的，但是有害无益，在泛型编程中则根本不可行。所以，任何 C+编程规范都不应该要求使用匈牙利记法，而在规范中选择禁用该法则是合理的。例 4 单入口，单出口（SESE，Single Entry,Single Exit）。历史上，有些编程规范曾经要求每个函数都只能有一个出口，也就意味着只能有一个 return 语句。这种要求对于支持异常和析构函数的语言而言已经过时了，在这样的语言中，函数通常都有多个隐含的出口。取而代之，应该遵循类似于第 5 条那样的标准，即直接提倡更简单的、更短小的函数，这样的函数本身更易于理解，更容易防错。参考文献 BoostLRG Brooks95 12 Constantine95 29 Keffer95p.1 Kernighan99 1.1,1.3,1.6-7 这是纯 C（K&R）风格的括号位置，如函数名所示。译者注 每个括号一行，如函数名所示。译者注 每个括号一行并缩进，如函数名所示。译者注 人月神话第 12 章“干将莫邪”（Sharp Tools）主要讨论工具问题。其中谈到：“项目经理必须考虑、计划、组织的工具到底有哪些呢？需要语言，语言的使用准则必须明确。”译者注 4 C+编程规范：101 条规则、准则与最佳实践 Lakos96 1.4.1,2.7 McConnell93 9,19 Stroustrup94 4.2-3 Stroustrup00 4.9.3,6.4,7.8,C.1 Sutter00 6,20 SuttHysl01 Code Complete 一书（此书新版已经于 2004 年底出版）的第 9 章“Data Names”。译者注 组织和策略问题 5 第 1 条 在高警告级别干净利落地进行编译 摘要 高度重视警告：使用编译器的最高警告级别。应该要求构建是干净利落的（没有警告）。理解所有的警告。通过修改代码而不是降低警告级别来排除警告。讨论 编译器是你的朋友。如果它对某个构造发出警告，一般表明代码中存有潜在的问题。成功的构建应该是无声无息的（没有警告的）。如果不是这样，你很快就会养成不仔细查看输出的习惯，从而漏过真正的问题（见第 2 条）。排除警告的正确做法是：（1）把它弄清楚；然后，（2）改写代码以排除警告，并使代码阅读者和编译器都能更加清楚，代码是按编写者的意图执行的。即使程序一开始似乎能够正确运行，也还是要这样做。即使你能够肯定警告是良性的，仍然要这样做。因为良性警告的后面可能隐藏着未来指向真正危险的警告。示例 例 1 第三方头文件。无法修改的库头文件可能包含引起警告（可能是良性的）的构造。如果这样，可以用自己的包含原头文件的版本将此文件包装起来，并有选择地为该作用域关闭烦人的警告，然后在整个项目的其他地方包含此包装文件。例如（请注意，各种编译器的警告控制语法并不一样）：/文件：myproj/my_lambda.h 包装了Boost的lambda.hpp/应该总是包含此文件，不要直接使用lambda.hpp。/注意：我们的构建现在会自动检查grep lambda.hpp。/Boost.Lambda 会产生一些已知无害的编译器警告。/在改正以后，我们将删除以下的编译指示，但此头文件仍然存在。/#pragma warning(push)/仅禁用此头文件#pragma warning(disable:4512)#pragma warning(disable:4180)#include#pragma warning(pop)/恢复最初的警告级别 6 C+编程规范：101 条规则、准则与最佳实践 例 2 “未使用的函数参数”（Unused function parameter）。检查一下，确认确实不需要使用该函数参数（比如，这可能是一个为了未来扩展而设的占位符，或者是代码没有使用的标准化函数签名中的一个必需部分）。如果确实不需要，那直接删除函数参数名就行了。/在一个用户定义的allocator中未使用hint /警告：unused parameter localityHint pointer allocate(size_type numObjects,const void*localityHint=0)return static_cast(mallocShared(numObjects*sizeof(T);/消除了警告的新版本 pointer allocate(size_type numObjects,const void*/*localityHint*/=0)return static_cast(mallocShared(numObjects*sizeof(T);例 3 “定义了从未使用过的变量”（Variable defined but never used）。检查一下，确认并不是真正要引用该变量。（RAII 基于栈的对象经常会引起此警告的误报，见第 13 条。）如果确实不需要，经常可以通过插入一个变量本身的求值表达式，使编译器不再报警。（这种求值不会影响运行时的速度。）/警告：variable lock is defined but never used void Fun()Lock lock;/可能消除了警告的新版本 void Fun()Lock lock;lock;/例 4 “变量使用前可能未经初始化”（Variable may be used without being initialized）。初始化变量（见第 19 条）。例 5 “遗漏了 return 语句”（Missing return）。有时候编译器会要求每个分支都有 return 语句，即使控制流可能永远也不会到达函数的结尾（比如：无限循环，throw 语句，其他的返回形式等）。这可能是一件好事，因为有时候你仅仅是认为控制不会运行到结尾。例如，没有 default组织和策略问题 7 情况的 switch 语句不太适应变化，应该加上执行 assert(false)的 default 情况（见第 68 条和第90 条）。/警告：missing return int Fun(Color c)switch(c)case Red:return 2;case Green:return 0;case Blue:case Black:return 1;/消除了警告的新版本 int Fun(Color c)switch(c)case Red:return 2;case Green:return 0;case Blue:case Black:return 1;default:assert(!should never get here!);/!string 的求值结果为false return-1;例 6 “有符号数/无符号数不匹配”（signed/unsigned mismatch）。通常没有必要对符号不同的整数进行比较和赋值。应该改变所操作的变量的类型，从而使类型匹配。最坏的情况下，要插入一个显式的强制转换。（其实不管怎么样，编译器都将为你插入一个强制转换，同时还会发出警告，因此还不如显式地先发而制之。）例外情况 有时候，编译器可能会发出烦人的甚至虚假的警告（即纯属噪声的警告），但是又没有提供消除的方法，这时忙于修改代码解决这个警告可能是劳而无功或者事倍功半的。如果遇到了这种罕见的情形，作为团队决定，应该避免对纯粹无益的警告再做无用功：单独禁用这个警告，但是要尽可能在局部禁用，并且编写一个清晰的注释，说明为什么必须禁用。参考文献 Meyers97 48 Stroustrup94 2.6.2 在 Effective C+一书中，该条款名为“不要对编译器警告信息视而不见”。其中谈到：“在使用了特定编译器警告信息并获取了一定经验之后，可以开始理解不同信息所代表的含义（常常与表面意思差异很大），而一旦有了经8 C+编程规范：101 条规则、准则与最佳实践 第 2 条 使用自动构建系统 摘要 一次按键就解决问题：使用完全自动化（“单操作”）的构建系统，无需用户干预即可构建整个项目。讨论 单操作的构建过程非常重要。它应该能将源文件可靠和可重复地转换为可以交付的软件包。现在已经有了大量自动构建工具，没有理由不用。所以，选择一种，用起来吧。我们曾经见到不少开发单位忽略了构建系统“单操作”这一需求。有些开发单位认为，用鼠标四处点击几下，运行一些实用工具来注册 COM/CORBA 服务器，手工复制一些文件，就是很不错的构建过程了。可是，我们都不应该将时间和精力浪费在机器可以干得更快更好的事情上。自动的、可靠的、单操作的构建是非常必要的。成功的构建应该无声无息，不产生任何警告（见第 1 条）。理想的构建过程不会出现干扰，只会出现一条日志信息：“构建成功”。构建有两种模式：增量构建和完全构建。增量构建只重新构建上次构建（可以是增量的或者完全的）以来发生改变的部分。注意：两次连续增量构建中的第二次构建不应该编写任何输出文件；否则，可能会出现依赖循环（见第 22 条），构建系统也可能会执行不必要的操作（比如，编写假的肯定要丢弃的临时文件）。一个项目的完全构建可能有不同形式。可以考虑通过改变许多基本特性，调整构建过程的参数，候选的特性包括目标架构，调试模式还是发布模式，以及范围（基本文件、所有文件、还是完整的安装文件）。一种构建设置能够生成产品的基本可执行文件和库，另一种设置可能还会生成附属文件，而完全构建则可能生成包括所有文件、第三方可重发行文件和安装代码在内的安装文件。随着项目日渐发展，不使用自动构建所带来的成本也会逐渐增加。如果没有从一开始就使用自动构建，时间和资源的浪费就将无可避免。更糟糕的情况是，到了不得不使用自动构建的时候，你所面临的压力将比项目开始时大得多。大型项目可能应该设置一个“构建管理员”，他的工作就是负责构建系统。验，可能你不会再理会某些警告。但是在忽略任何一个警告前，必须精确理解编译器试图在告诉你什么，这非常重要。”译者注 组织和策略问题 9 参考文献 Brooks9513,19 Dewhurst031 GnuMake Stroustrup009.1 10 C+编程规范：101 条规则、准则与最佳实践 第 3 条 使用版本控制系统 摘要 常言道，好记性不如烂笔头：请使用版本控制系统（Version Control System，VCS）。永远不要让文件长时间地登出。在新的单元测试通过之后，应该频繁登入。确保登入的代码不会影响构建成功。讨论 几乎所有大一点的项目都需要不只一个开发人员和一周以上的开发时间。在这样的项目中，需要比较同一文件的各个历史版本，以确定修改是何时（以及/或者由谁）进行的；需要控制和管理源代码的变更。如果有多个开发人员，他们将会并行地进行修改，可能会在同一时间修改同一文件的不同部分。此时，就需要能对文件进行自动登出/版本管理的工具了，有些情况下还需要并发编辑的合并功能。版本控制系统能够自动化和控制登出、版本管理及合并操作。版本控制系统能够比人工实施更快更正确。而且我们也不需要在管理琐事上浪费时间编写软件才是我们的工作。即使是单独工作的开发人员，也有脑子短路的瞬间，需要搞清楚何时为什么引入了某个错误或者进行了某个修改。我们都难免如此。版本控制系统能够自动地跟踪每个文件的历史，使我们能够“让时光倒流”。问题并不在于你是否需要从历史中寻找答案，而在于你何时需要。不要破坏构建。版本控制系统中的代码必须总能构建成功。由于目前能够找到大量的版本控制系统，我们没有任何借口将其拒之门外。最廉价也最流行的版本控制系统是 cvs（见本条参考文献）。这个工具非常灵活，提供了 TCP/IP 访问功能，可以选择增强安全性（提供使用 ssh 协议作为后端），可以通过脚本编程实现极佳的管理功能，甚至还有图形界面。许多其他的版本控制系统产品要么将 cvs 作为模仿的标准，要么是以其为基础再构建新的功能。例外情况 只有一个程序员且从头至尾只需一周的项目，可能不需要版本控制系统。参考文献 BetterSCM Brooks95 11,13 CVS 此处作者意在强调：这只是迟早的事情。译者注 组织和策略问题 11 第 4 条 做代码审查 摘要 审查代码：更多的关注有助于提高质量。亮出自己的代码，阅读别人的代码。互相学习，彼此都会受益。讨论 好的代码审查过程对开发团队有许多好处。通过来自同伴的良性压力提高代码质量。找出错误、不可移植的代码（如果适用）和潜在的扩展问题。通过思想交流获得更好的设计和实现。快速培养新同事和入门者。在团队中形成共同的价值观和集体主义。增强整体实力，提升自信心、动力和职业荣誉感。许多开发单位现在既不奖励高质量的代码和高质量的团队，也不投入时间和资金予以鼓励。我们估计几年之内这种情况仍然会存在，但是趋势已经在缓慢变化，这部分是因为软件安全性需求的不断增加。代码审查恰恰有助于提高软件的安全性，而且还是内部培训的一种极佳方法（而且没有成本）！如果老板现在还不支持代码审查过程，那就先从提高管理层的认识做起（提示：一开始先给他们看看这本书），同时尽最大努力想各种办法腾出时间进行审查。这种时间是值得花的。代码审查应该成为软件开发周期中的常规环节。如果能够与同事就奖惩制度达成一致，那就更好了。代码审查无需太形式主义，最好通过书面形式进行一封简单的电子邮件就足够了。这样能够更容易地跟踪你自己的过程，避免重复。在审查别人的代码时，可能需要保存一份核对表以备参考。举贤不避亲，我们推荐本书的目录，它就是一个很好的核对表。愿你使用愉快！小结：我们知道这是老调重弹，但还是不得不说。我们的天性都讨厌代码审查，但是内心又有一个小小的天才程序员乐此不疲，因为它富于成效，而且能够获得更好的代码和更可靠的应用程序。参考文献 12 C+编程规范：101 条规则、准则与最佳实践 Constantine95 10,22,33 McConnell93 24 MozillaCRFAQ