《源程序文档化PPT优秀课件》由会员分享，可在线阅读，更多相关《源程序文档化PPT优秀课件（36页珍藏版）》请在金锄头文库上搜索。
1、软件工程研讨 源程序文档化,第六组 组员： 12122208 陈帅 12123298 马敏 12123249 雷晴 12123256 邱可艺,2014.12.16,1,变量、常量和函数的命名规范,2,变量名所有字母小写，单词之间用下划线(_)分开，类成员变量以下划线结束。 普通变量命名(Common Variable Names) 比如：,类数据组成变量命名(Class Data Members) 数据成员（又叫实例变量或者成员变量）的命名与普通变量一样， 全部字母小写，可选的下划线分隔符，但应该以下划线结束。,string table_name_; / 可以以下划线结束 string tab
2、lename_; / 可以,变量命名(Variable Names),string table_name; / 可以使用下划线 string tablename; / 可以全部字母小写 string tableName; / 糟糕大小写混合,3,结构体成员变量命名(Struct Variables) 结构体成员变量和普通变量命名规则一致，且不像类 成员变量以下划线结束。,struct UrlTableProperties string name; int num_entries; ,全局变量命名(Global Variables) 全局变量的使用较为罕见，但当用到时， 考虑以前缀g_开头或标以
3、其他记号，以便与局部变量区分。,4,常量命名(Constant Names),K后跟混合大小写的名称：kDaysInAWeek。所有编译时常量，不管是被声明为局部、全局还是作为类的成员，都应该遵守与其他变量命名有轻微差别的命名约定：k后跟单词首字母大写的名称：,const int kDaysInAWeek = 7;,5,函数命名(Function Names),正规函数名应该以大写字母开头，单词首字母大写，不使用下划线。如果函数可能因错误而崩溃，应该在函数名后加上OrDie。这仅适用于那些被产品代码调用或者正常操作有可能引起错误的函数。,AddTableEntry() DeleteUrl()
4、OpenFileOrDie(),6,访问器和修改器(Accessors and Mutators) 访问器和修改器（get和set函数）应该与它们关联的变量名匹配。下面显示了一个类的部分摘录，它有一个实例变量num_entries,class MyClass public: . int num_entries() constreturn num_entries; void set_num_entries(int num_entries)num_entries = num_entries; private: int num_entries_; ;,你也可以使用小写字母和下划线来命名非常短小的内联
5、函数。比如，如果一个函数的调用开销很小，在循环调用时，没必要缓存其值，这时，小写字母命名是允许的。,7,对文件、类、函数、变量和逻辑功能段进行注释的规范,8,文件注释(File Comments),每个文件都应该提供版权信息，然后是文件内容的综合性描述。 合法公告和作者信息行(Legal Notice and Author Line) 每个文件都应依次包括以下条目， 1、版权声明(比如Copyright 2008 Google Inc.)； 2、一个许可引用。选择适合你项目使用的许可引用（比如Apache 2.0、BSD、LGPL、GPL） 3、作者信息行说明文件原始作者,如果你对原始作者的文
6、件做了实质性修改，可以在作者信息行加上你的名字。当其他开发者有问题时，这样可以方便他们正确地联系到修改者。,9,文件内容注释(File Contents) 每个文件都应该在其版权信息及作者信息后面和内容前面有一个内容描述性的注释。 通常，头文件描述它所声明的类的目的及用法。而源文件则应该包含更多有关实现和技巧性算法的讨论信息。但如果你觉得这些信息对于头文件的阅读者更有用，可以将其放在头文件中，但在源文件中应该注明其文档在头文件中。不要在头文件和源文件中重复注释，这样容易造成歧义。,10,类注释(Class Comments),每个类定义都应该伴随有说明其目的和用法的注释。,/ 遍历Gargan
7、tuanTable的内容。用法示例： / GargantuanTableIterator* iter = table-NewIterator(); / for(iter-seek(“foo”);!iter-done();iter-next() / process(iter-key(),iter-value(); / / delete iter; Class GargantuanTableIterator .,如果你在文件开始就已对类进行了详细描述，可以在类实现部分简单地声明“参见文件开始注释部分的完整描述”，但注意，这里还是要添加少量注释。,11,函数注释(Function Comments)
8、,函数声明部分的注释描述函数的用法，实现部分的注释描述函数实现的操作。,每个函数声明的前面都应该有一个描述函数功能和用法的注释。这些注释应该是描述性(Opens the file)，而不是祈使性的（Open the file），注释仅仅描述函数能够完成什么功能而不是函数是怎么实现的，这些应该在函数实现的注释中。 在函数声明注释中应该提到的信息类型： 1、输入和输出； 2、对于类成员函数，在该方法的调用周期外，对象是否有引用参数，它是否会释放这些引用； 3、如果一个函数申请了内存，它必须释放它们； 4、参数是否可以是空； 5、函数的使用方法是否会影响其性能； 6、如果函数可重入。它是怎么实现同步
9、的？,12,例子：,/ 返回这个表的一个迭代器 / 当遍历结束时，由客户程序负责迭代器的释放 / 一旦此迭代器的创建者GargantuanTable对象被释放 / 客户程序不可再使用此迭代器 / / 迭代器被初始化为指向表的开始 / / 这个方法等价于： / Iterator *iter = table-NewIterator(); iter-seek(“”); return iter; / 如果你想立即寻找返回的迭代器中的另一个位置，使用NewIterator()更快，而/ 且避免了额外的查找。 Iterator* getIterator()const,然而，避免不必要的冗长注释且不要添加显
10、而易见的注释。比如下例外中，返回假的情况就没必要，因为这很明显：,/ 如果表已被占满，不能再容纳实体，则返回真 bool IsTableFull();,13,当给构造和析构函数加注释时，注意，读者清楚地知道这些函数的作用，所以诸如“销毁这个对象”的注释毫无意义。注释内容应该说明构造函数怎样处理参数（比如它是否取得指针的控制权）和析构函数怎么完成清理工作。如果这些不很重要，可以省略它们。文件的开头注释中没有关于析构函数的注释是很正常的。,函数定义注释(Function Definition) 每个函数都应该有一个注释来描述函数的功能和其完成这些功能的实现技巧（如果有的话）。比如，你在函数定义注释
11、中，你可以描述编码中用到的技巧，给出大致的执行步骤或者解释一下你选择这种实现而不使用其他替代方法的原因。比如，你可能需要说明为什么函数前半部分需要锁而后半部分不需要。 注意，不能简单地重复头文件或者其他地方函数声明部分的注释。可以再次概括一下函数的功能，但焦点应该是函数是怎么实现功能的。,14,变量注释(Variable Comments),通常，一个变量的实际名称已经提供了足够和描述信息来说明其用途。但某些情况下，可能需要更多注释。,类数据成员(Class Data Members) 每个类数据成员（也称实例变量或者成员变量）应该有一个描述其用途的注释。如果这个变量能取得具有特殊意义的标志值
12、，比如NULL或-1，则需要加以说明。比如：,Private: /记录表中实体的总数 /用于确保不打破数量限制。 /-1意味着表的实体数未知 int num_total_entries;,15,全局变量(Global Variables) 和数据成员一样，所有全局变量应该有一个描述其功能及其意义的注释。比如,/ 所有本次回归测试使用到的测试用例数 cosnt int kNumTestCases = 6;,实现注释(Implementation Comments) 在实现中，应该对你代码技巧性的、不明显的、有趣的或者重要的部分进行注释。 类数据成员(Class Data Members) 技巧性
13、的和复杂难懂的代码块前应该有注释：,/ Divide result by two, taking into account that x / contains the carry from the add for(int i = 0;i size();i+) x = (x 1; X ,16,行注释(Line Comments) 同样，当行代码中有不明显的地方时，也需要在其行末添加注释。这种行末注释应该以2个空白与代码分开。,/ If we have enough money, mmap the data portion too. mmap_budget = max(0,mmap_budget
14、index_-length(); if(mmap_budget = data_size / Error already logged.,可以看到，这里即有描述代码功能的注释，也有提醒函数返回时错误已经被记录的注释。 如果有多行注释，将它们整齐排列将增加可读性。,DoSomething(); / Comment here so the comments line up DoSomethingElseThatIsLong(); / Comment here so there are two spaces / between the code and the comment / One space
15、before commnet when opening a new scope is allowed, / thus the comment lines up with the following comments and code DoSomethingElse(); / Two spaces before line comments normally ,17,逻辑功能段进行注释,当给函数传入NULL、布尔值和整型值串时，应该增加注释以说明这些值的意义，或者你可以使用常量使代码自文档化。比较以下两段代码：,bool success = CalculateSomething(interesti
16、ng_value, 10, false, NULL);/这些参数都是什么意思？,VS,bool success = CalculateSomething(interesting_value, 10, /默认基数 flase,/非第一次调用 NULL);/无回调,18,也可以使用替代方案，常量或自描述的变量：,const int kDefaultBaseValue = 10; const bool kFirstTimeCalling = false; callback *null_callback = NULL; bool success = CalculateSomething(interesting_value, kDefaultBaseValue,
