C++注释规范-技术架构部C++基础架构组.docVIP

PAGE PAGE 1 C++注释规范 版本：1.0 制定部门：技术架构部C++基础架构组 2006.8 目录 TOC \o 1-3 \h \z \u 1 说明 3 2 注释种类 3 2.1 重复代码 3 2.2 解释代码 3 2.3 代码标记 3 2.4 概述代码 3 2.5 代码意图说明 4 2.6 传达代码无法表达的信息 4 3 注释原则 4 3.1 站在读者的立场编写注释 4 3.2 注释无法取代良好的编程风格 4 3.3 好注释能在更高抽象层次上解释我们想干什么 5 4 规范细则 5 4.1 文件注释规范 5 4.2 名字空间注释规范 6 4.3 类定义注释规范 7 4.4 数据声明注释规范 8 4.5 函数注释规范 8 4.6 代码标记注释规范 10 5 FAQ 10 5.1 枚举值需要注释吗？ 10 5.2 前置条件、后置条件和不变式有必要注释出来吗？ 10 5.3 写注释太耗时间怎么办？ 11 5.4 有效的注释是指什么？ 11 参考书目 11 参考工具 11 1 说明 本文档用于规范C++代码中注释的编写。规范中提出的多数注释格式都来源于文档生成工具doxygen，所以遵从本规范进行注释的C++代码都可以使用doxygen生成美观一致的代码文档。 同时另一方面，美观绝非衡量文档质量的唯一标准。文档内容准确与否，是否充分，以及语言组织是否清晰流畅，这些都是决定一份文档质量的重要标准。遗憾的是，这些标准当中有不少需要通过主观加以判断，很难进行明确的规范。 所以我们将尽可能的提供明确的评判标准，同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于众多先驱多年的开发经验。遵循它们不仅有助于生成一份美观的代码文档。更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计的合理性，同时也为编写单元测试提供更多的帮助。 2 注释种类 2.1 重复代码 重复性注释只是用不同文字把代码的工作又描述一次。他除了给读者增加阅读量外，没有提供更多信息。 2.2 解释代码 解释性注释通常用于解释复杂、敏感的代码块。在这些场合他们能派上用场，但通常正是因为代码含混不清，才体现出这类注释的价值。如果代码过于复杂而需要解释，最好是改进代码，而不是添加注释。使代码清晰后再使用概述性注释或者意图性注释。 2.3 代码标记 标记性注释并非有意留在代码中，他提醒开发者某处的工作未做完。在实际工作中，我们经常会使用这些注释作为程序骨架的占位符，或是已知bug的标记。 2.4 概述代码 概述性注释是这么做的：将若干代码行的意思以一两句话说出来。这种注释比重复性注释强多了，因为读者读注释能比读代码更快。概述性注释对于要修改你代码的其他人来说尤其有用。 2.5 代码意图说明 意图性注释用来指出要解决的问题，而非解决的方法。意图性注释和概述性注释没有明显的界限，其差异也无足轻重，都是非常有效的注释。 2.6 传达代码无法表达的信息 某些信息不能通过代码来表达，但又必须包含在源代码中。这种注释包括版权声明、作者、日期、版本号等杂项信息；与代码设计有关的注意事项；优化注记；和doxygen要求的注释等等。 3 注释原则 编写一份好的注释，并不比编写一段好的代码更容易，以至于我们不得不特别强调编写注释应该遵循的三个原则： 3.1 站在读者的立场编写注释 我们的代码将会面对很多不同的读者。其中一类是代码复审者。他们希望看到的是准确的注释说明，小心地编写注释避免出现可笑的错误是最重要的。 接下来的读者是代码的用户，这部分人大多并不关心代码中使用了何等绝妙的高超技术。事实上，代码能干什么，以及如何正确的使用更令他们感兴趣。所以当我们在对那些可能面向用户的地方注释时，多多考虑一下用户的实际需要并非多余。 最后一类，怎么说呢，作为代码的维护者，他们整天要和成打的代码打交道，渴望能够用最少的时间找到目标代码。所以，如果代码中有一些提纲挈领的注释，可以供他们用作节约代码阅读时间的索引，毫无疑问，这会令大家都工作得更加开心。 3.2 注释无法取代良好的编程风格 引用《代码大全》中的观点，在代码层文档中起主要作用的因素并非注释，而是良好的编程风格。编程风格包括良好的程序结构、直率易懂的方法、有意义的变量名和函数名、具名常量、清晰的布局、以及最低复杂度的控制流及数据结构。关于命名方面的规范参见《C++命名规范》。 虽然本篇规范讨论的重点并非编程风格，但是无论什么时候，我们都应该明白，对于精心编写的代码而言，注释不过是美丽衣裳上的小饰物而已。 3.3 好注释能在