源程序文档化课件

源程序文档化
访问器和修改器(Accessors and Mutators) 访问器和修改器（get和set函数）应该与它们关联的变量名匹 配。下面显示了一个类的部分摘录，它有一个实例变量 num_entries源自class MyClass{
public:
...
int
num_entries()
const{return
源程序文档化
类注释(Class Comments)
每个类定义都应该伴随有说明其目的和用法的注释。
// 遍历GargantuanTable的内容。用法示例：
// GargantuanTableIterator* iter =
table->NewIterator();
//
for(iter->seek(“foo”);!iter-
>done();iter->next()){
//
process(iter->key(),iter-
>value();
// }
// delete iter;
Class GargantuanTableIterator{
...
如果你在文件开始就已对类进行了详细描述，可以在类实现 部分简单地声明“参见文件开始注释部分的完整描述”，但注 意，这里还是要添加少量注释。
普通变量命名(Common Variable Names) 比如：
string table_name; string tablename; string tableName;
// 可以－使用下划线 // 可以－全部字母小写 // 糟糕－大小写混合
类数据组成变量命名(Class Data Members) 数据成员（又叫实例变量或者成员变量）的命名与普通变量一样， 全部字母小写，可选的下划线分隔符，但应该以下划线结束。
源程序文档化
函数注释(Function Comments)
函数声明部分的注释描述函数的用法，实现部分的注释描述 函数实现的操作。
每个函数声明的前面都应该有一个描述函数功能和用法的注 释。这些注释应该是描述性(Opens the file)，而不是祈使性 的（Open the file），注释仅仅描述函数能够完成什么功能 而不是函数是怎么实现的，这些应该在函数实现的注释中。 在函数声明注释中应该提到的信息类型： 1、输入和输出； 2、对于类成员函数，在该方法的调用周期外，对象是否有 引用参数，它是否会释放这些引用； 3、如果一个函数申请了内存，它必须释放它们； 4、参数是否可以是空； 5、函数的使用方法是否会影响其性能； 6、如果函数可重入。它是怎么实现同步的？
源程序文档化
例子：
// 返回这个表的一个迭代器 // 当遍历结束时，由客户程序负责迭代器的释放 // 一旦此迭代器的创建者GargantuanTable对象被释放 // 客户程序不可再使用此迭代器
num_entries;}
void
set_num_entries(int
num_entries){num_entries = num_entries;}
private:
int num_entries_;
};
你也可以使用小写字母和下划线来命名非常短小的内联函数。 比如，如果一个函数的调用开销很小，在循环调用时，没必 要缓存其值，这时，小写字母命名是允许的。
源程序文档化
对文件、类、函数、变量和逻 辑功能段进行注释的规范
源程序文档化
文件注释()
每个文件都应该提供版权信息，然后是文件内容的综合性描述。 合法公告和作者信息行(Legal Notice and Author Line) 每个文件都应依次包括以下条目，
1、版权声明(比如Copyright 2008 Google Inc.)； 2、一个许可引用。选择适合你项目使用的许可引用（比如 Apache 2.0、BSD、LGPL、GPL） 3、作者信息行说明文件原始作者
}
全局变量命名(Global Variables) 全局变量的使用较为罕见，但当用到时， 考虑以前缀g_开头或标以其他记号，以便与局部变量区分。
源程序文档化
常量命名(Constant Names)
K后跟混合大小写的名称：kDaysInAWeek。所有编译时常量， 不管是被声明为局部、全局还是作为类的成员，都应该遵守 与其他变量命名有轻微差别的命名约定：k后跟单词首字母大 写的名称：
如果你对原始作者的文件做了实质性修改，可以在作者信息行加上 你的名字。当其他开发者有问题时，这样可以方便他们正确地联系 到修改者。
源程序文档化
文件内容注释() 每个文件都应该在其版权信息及作者信息后面和内容前面有 一个内容描述性的注释。 通常，头文件描述它所声明的类的目的及用法。而源文件则 应该包含更多有关实现和技巧性算法的讨论信息。但如果你 觉得这些信息对于头文件的阅读者更有用，可以将其放在头 文件中，但在源文件中应该注明其文档在头文件中。不要在 头文件和源文件中重复注释，这样容易造成歧义。
string table_name_; string tablename_;
// 可以－以下划线结束 // 可以
源程序文档化
结构体成员变量命名(Struct Variables) 结构体成员变量和普通变量命名规则一致，且不像类 成员变量以下划线结束。
struct UrlTableProperties{ string name; int num_entries;
const int kDaysInAWeek = 7;
源程序文档化
函数命名(Function Names)
正规函数名应该以大写字母开头，单词首字母大写，不使用下 划线。如果函数可能因错误而崩溃，应该在函数名后加上OrDie。 这仅适用于那些被产品代码调用或者正常操作有可能引起错误 的函数。
AddTableEntry() DeleteUrl() Open()
软件工程研讨
源程序文档化
第六组 组员： 12122208 12123298 12123249 12123256 邱可艺
源程序文档化
2014.12.1 6
变量、常量和函数的命名规范
源程序文档化
变量命名(Variable Names)
变量名所有字母小写，单词之间用下划线(_)分开，类成员变量 以下划线结束。