C++注释规范概要1.doc

C++注释规范 版本：1.0 制定部门： 质量管理部 目录 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生成美观一致的代码文档。同时另一方面，美观绝非衡量文档质量的唯一标准。文档内容准确与否，是否充分，语言组织是否清晰流畅，都是决定一份文档质量的重要标准。遗憾的是，这些标准当中有不少通过主观加以判断，很难明确规范。所以尽提供的评判标准同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于年的开发经验。遵循它们不仅有助于生成一份的代码文档。更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计，同时也为单元测试。是代码复审者。，小心编写注释避免出现可笑的错误是最重要的。 接下来的读者是代码的这部分大多并不关心代码中使用了何等绝妙的高超技术更感兴趣。所以 最后一类，怎么说呢，，，占据单独一行并用@date加以标记 也可以包含以下一些可选内容： 文件内容的详细描述，紧接简要描述之后并与其以一空行隔开 文件版本，占据单独一行并用@version加以标记，使用maj.min格式表示，其中maj为主版本号，min为次版本号。 文件注释需要放到每个代码文件的起始位置。这里提供了一个完整的格式示例，多数情况下可以完全照搬其格式。 /** * @file Shape.h * @brief 包含图形基类Shape * * 本示例文件中包含了类Shape的定义，以及此处省去的十余字… * * @author wenruiyun@ * @version 1.0 * @date 2006 */ 请注意，正如我们《C++编码规范》中提到的。在C++世界中，我们不应该使用C风格的/*…*/块注释，而应该使用C++风格的//行注释。是的，我们应该毫不动摇的恪守这一条款。但是，由于我们希望借助doxygen帮助我们生成漂亮的文档，如果我们在对文件注释的风格选取上毫不通融的话，doxygen会为我们生成一大片可笑的空白： 00001 00002 00003 00004 00005 00006 00007 00008 00009 00010 00011 #pragma once 00012 00013 #include utility.h 00014 00018 namespace MyGraph 00019 { 为了避免这样的尴尬场面，我们只好破例留下了这段C风格文件注释。好在这是唯一必须使用C风格注释才能令doxygen满意的地方，跨过文件注释之后，我们仍然应该虔诚的遵循C++的行注释风格。 4.2 名字空间注释规范 名字空间是一个好东西，编写名字空间注释的要点是，不要试图把这个名字空间介绍的面面俱到。简单的介绍设置这个名字空间的意图或是完全不要注释都是不错的选择。 如果决定要为名字空间添加注释，有一点非常重要：无论如何不要试图给同一个名字空间提供两份不同的注释，不管这些注释是否位于同一个代码文件中。一个有效的做法是，一开始不用给名字空间添加任何注释，先用doxygen生成文档，发现哪个名字空间缺少文档，再挑选一个最合适的代码文件进行名字空间注释。下面是一个名字空间注释的格式示例： /// @brief 包含一系列图形元素 /// /// 在MyGraph名字空间中，包含一系列图形元素，所有的这些图形元素都派生于Shape类 namespace MyGraph { /// @brief 提供对MyGraph中所有图形元素公共特性的抽象 /// /// 具备可显示，可移动等特征的图形基类，所有其他的图形元素都派生自该类型。 /// MyGraph的用户多数情况下都会使用那些具体的Shape派生类，而不是Shape。